Build a Simple Catalog

Learn the basics of the Square Catalog API by creating a simple product catalog for a cafe that serves coffee in small and large sizes, with skim or whole milk.

To build this catalog, you call the UpsertCatalogObject endpoint to create the following catalog objects to represent the for-sale item (Coffee). You include two variations (Small Coffee and Large Coffee) of the sale item, a CatalogTax object as taxes applied to the coffee item, and two optional modifications (with Skim Milk and Whole Milk).

A CatalogItem object named Coffee for coffee drinks.
Two CatalogItemVariation objects named Small and Large for the coffee drink size variations.
A CatalogTax object for the sales tax applied when a payment is made on the coffee drink order.
Two CatalogModifier objects for the two milk choices.
A CatalogModifierList object to hold the two CatalogModifier objects to apply the milk choices to the coffee item.

The following steps are generally applicable to creating catalog objects of other types, except for uploading an image object. For information about how to upload an image to a catalog and attach it to an item, item variation, or category, see Work with Images.

Prerequisites

You have a Square account enabled for payment processing. If you haven't enabled payment processing on your account (or you're not sure), visit squareup.com/activation.

The following is also assumed:

You are familiar with HTTPS. If this is your first time working with HTTPS, see TLS and HTTPS before continuing.

Link to section

Information you need

To use the steps in this topic, you need the following:

You need a valid access token - You should test with Sandbox credentials whenever possible. For more information, see Access Tokens and Other Square Credentials.

Link to section

Step 1: Add a coffee item to a catalog

Important

When creating an item, you must also specify at least one variation. Otherwise, you get an INVALID_REQUEST error.

To add a coffee item to a catalog as a product offering of a seller, call the UpsertCatalogObject endpoint to create a CatalogItem object in the catalog. This is shown in the following REST API example:

Upsert catalog object

In this example, the Coffee item has two variations (Small and Large).

The #coffee ID is a temporary ID, serving as a placeholder for the permanent ID that the Square API generates and returned in the response. In the same request payload where the temporary ID is defined, you can use the temporary ID value to reference this to-be-created object. The two variations in this example use #coffee to identify its parent item. If these variations were created in a separate request, you must use their Square-generated permanent ID values to reference them.

Because the UpsertCatalogObject endpoint is used to create other catalog objects, the data object you specify must match the specified type property value. In this example, you must set the item_data property to an appropriate CatalogItem object to match the ITEM type and set the item_variation_data property to an appropriate CatalogItemVariation object to match the ITEM_VARIATION type. Similarly, to set up a discount to be applied to an order, you must specify an appropriate CatalogDiscount object on the discount_data field while setting the type value to DISCOUNT. In summary, the type property must match the {object_type}_data property.

When the request is successful, you get a 200 OK response with a payload similar to the following:

{
  "catalog_object": {
    "type": "ITEM",
    "id": "FX3LTXC2CCFCGHLGMSFLBSDO",
    "updated_at": "2021-06-15T18:48:16.262Z",
    "version": 1623782896262,
    "is_deleted": false,
    "present_at_all_locations": true,
    "item_data": {
      "name": "Coffee",
      "description": "Coffee Drink",
      "abbreviation": "Co",
      "variations": [
        {
          "type": "ITEM_VARIATION",
          "id": "OXRR3XANRU5TEQ3FQMDW5IJK",
          "updated_at": "2021-06-15T18:48:16.262Z",
          "version": 1623782896262,
          "is_deleted": false,
          "present_at_all_locations": true,
          "item_variation_data": {
            "item_id": "FX3LTXC2CCFCGHLGMSFLBSDO",
            "name": "Small",
            "ordinal": 0,
            "pricing_type": "FIXED_PRICING",
            "price_money": {
              "amount": 300,
              "currency": "USD"
            },
            "stockable": true
          }
        },
        {
          "type": "ITEM_VARIATION",
          "id": "3EFNOI25E4NUK53CU4KMUHXX",
          "updated_at": "2021-06-15T18:48:16.262Z",
          "version": 1623782896262,
          "is_deleted": false,
          "present_at_all_locations": true,
          "item_variation_data": {
            "item_id": "FX3LTXC2CCFCGHLGMSFLBSDO",
            "name": "Large",
            "ordinal": 1,
            "pricing_type": "FIXED_PRICING",
            "price_money": {
              "amount": 350,
              "currency": "USD"
            },
            "stockable": true
          }
        }
      ],
      "product_type": "REGULAR"
    }
  },
  "id_mappings": [
    {
      "client_object_id": "#coffee",
      "object_id": "FX3LTXC2CCFCGHLGMSFLBSDO"
    },
    {
      "client_object_id": "#small_coffee",
      "object_id": "OXRR3XANRU5TEQ3FQMDW5IJK"
    },
    {
      "client_object_id": "#large_coffee",
      "object_id": "3EFNOI25E4NUK53CU4KMUHXX"
    }
  ]
}

Note that the response returns the ID mapping between the temporary ID (id_mappings.client_object_id) value and the Square-generated ID (object_id) value. From now on, you must reference these objects by their respective object_id values.

Link to section

Step 2: Create a CatalogTax object for the coffee drink

In most locales, a sales tax must be levied on a sold product. To support taking taxes on an order, you must first create a CatalogTax object to set up the tax to be applied when the payment is made on the order.

The following code example shows how to create a tax object and add it to the catalog:

Upsert catalog object

In this example, the drink tax is 7.5% of the pre-tax subtotal of an order.

When successful, the request returns a 200 OK response with the payload similar to the following:

{
  "catalog_object": {
    "type": "TAX",
    "id": "TEROS7KLG76NDY4J7TYFZVGA",
    "updated_at": "2021-06-15T19:12:49.613Z",
    "version": 1623784369613,
    "is_deleted": false,
    "present_at_all_locations": true,
    "tax_data": {
      "name": "Drink Tax",
      "calculation_phase": "TAX_SUBTOTAL_PHASE",
      "inclusion_type": "ADDITIVE",
      "percentage": "7.5",
      "applies_to_custom_amounts": true,
      "enabled": true
    }
  },
  "id_mappings": [
    {
      "client_object_id": "#sales_tax",
      "object_id": "TEROS7KLG76NDY4J7TYFZVGA"
    }
  ]
}

Alternatively, you can combine the calls to create the Coffee item with the Small and Large variations and the Drink Tax object into a single call to the BatchUpsertCatalogObjects endpoint, as shown:

Batch upsert catalog objects

Link to section

Step 3: Create a modifier list to contain two modifiers

To enable sellers to offer the choices of adding skim milk and whole milk to the coffee drink, you can create two catalog modifiers to apply to the Coffee item. One way to add the modifiers is to create a modifier list containing individual modifiers as its entries.

The following example shows how to call the UpsertCatalogObject endpoint to create the CatalogModifierList object with two CatalogModifier objects for Skim Milk and Whole Milk:

Upsert catalog object

The successful operation returns a 200 OK response with a payload similar to the following:

{
  "catalog_object": {
    "type": "MODIFIER_LIST",
    "id": "ZVSGY6U63IGCZQL4IOPZAKYW",
    "updated_at": "2020-06-15T20:01:39.58Z",
    "version": 1623784369656,
    "is_deleted": false,
    "present_at_all_locations": true,
    "modifier_list_data": {
      "name": "Milk Options",
      "modifiers": [
        {
          "type": "MODIFIER",
          "id": "MNXLZRO2PIBULOX2RX56DG25",
          "updated_at": "2020-06-15T20:01:39.58Z",
          "version": 1623784369656,
          "is_deleted": false,
          "present_at_all_locations": true,
          "modifier_data": {
            "name": "Whole Milk",
            "price_money": {
              "amount": 125,
              "currency": "USD"
            },
            "ordinal": 0,
            "modifier_list_id": "ZVSGY6U63IGCZQL4IOPZAKYW"
          }
        },
        {
          "type": "MODIFIER",
          "id": "Q6R5X5VMSZTYVKM37QRHNZWM",
          "updated_at": "2020-06-15T20:01:39.58Z",
          "version": 1623784369656,
          "is_deleted": false,
          "present_at_all_locations": true,
          "modifier_data": {
            "name": "Skim Milk",
            "price_money": {
              "amount": 130,
              "currency": "USD"
            },
            "ordinal": 1,
            "modifier_list_id": "ZVSGY6U63IGCZQL4IOPZAKYW"
          }
        }
      ]
    }
  },
  "id_mappings": [
    {
      "client_object_id": "#modifier_list",
      "object_id": "ZVSGY6U63IGCZQL4IOPZAKYW"
    },
    {
      "client_object_id": "#whole_milk",
      "object_id": "MNXLZRO2PIBULOX2RX56DG25"
    },
    {
      "client_object_id": "#skim_milk",
      "object_id": "Q6R5X5VMSZTYVKM37QRHNZWM"
    }
  ]
}

For the modifiers in the modifier list be applied to the Coffee item, you must have the resultant modifier list applied to the Coffee item, as explained in step 4.

Link to section

Step 4: Apply the modifier list to the coffee item

To apply the modifier list created in step 3, call the UpdateItemModifierLists endpoint as shown in the following example:

Update item modifier lists

If successful, the operation returns a 200 OK response with a payload similar to the following:

{
  "updated_at": "2020-06-15T18:36:39.58Z"
}

Alternatively, you can call the BatchUpsertCatalogObjects endpoint to create a modifier list with appropriate modifier entries and add the modifier list to the Coffee item, together with the required item variations, in a single call to create all related CatalogObject instances at once.

Link to section

Step 5: Verify the catalog you just built

After building your catalog, you can view and verify it by calling the ListCatalog endpoint to inspect the catalog items. The following request shows an example:

List catalog

In response, the payload contains the catalog objects:

{
  "objects": [
    {
      "type": "ITEM",
      "id": "FX3LTXC2CCFCGHLGMSFLBSDO",
      "updated_at": "2021-06-15T18:48:16.262Z",
      "version": 1623782896262,
      "is_deleted": false,
      "present_at_all_locations": true,
      "item_data": {
        "name": "Coffee",
        "description": "Coffee Drink",
        "abbreviation": "Co",
        "modifier_list_info": [
          {
            "modifier_list_id": "ZVSGY6U63IGCZQL4IOPZAKYW",
            "enabled": true
          }
        ],
        "variations": [
          {
            "type": "ITEM_VARIATION",
            "id": "3EFNOI25E4NUK53CU4KMUHXX",
            "updated_at": "2021-06-15T18:48:16.262Z",
            "version": 1623782896262,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_variation_data": {
              "item_id": "FX3LTXC2CCFCGHLGMSFLBSDO",
              "name": "Large",
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 350,
                "currency": "USD"
              }
            }
          },
          {
            "type": "ITEM_VARIATION",
            "id": "OXRR3XANRU5TEQ3FQMDW5IJK",
            "updated_at": "2021-06-15T18:48:16.262Z",
            "version": 1623782896262,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_variation_data": {
              "item_id": "FX3LTXC2CCFCGHLGMSFLBSDO",
              "name": "Small",
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 300,
                "currency": "USD"
              }
            }
          }
        ],
        "product_type": "REGULAR"
      }
    },
    {
      "type": "TAX",
      "id": "TEROS7KLG76NDY4J7TYFZVGA",
      "updated_at": "2021-06-15T19:12:49.613Z",
      "version": 1623784369613,
      "is_deleted": false,
      "present_at_all_locations": true,
      "tax_data": {
        "name": "Drink Tax",
        "calculation_phase": "TAX_SUBTOTAL_PHASE",
        "inclusion_type": "ADDITIVE",
        "percentage": "7.5",
        "applies_to_custom_amounts": true,
        "enabled": true
      }
    },
    {
      "type": "MODIFIER_LIST",
      "id": "ZVSGY6U63IGCZQL4IOPZAKYW",
      "updated_at": "2020-06-15T20:01:39.58Z",
      "version": 1623784369656,
      "is_deleted": false,
      "present_at_all_locations": true,
      "modifier_list_data": {
        "name": "Milk Options",
        "modifiers": [
          {
            "type": "MODIFIER",
            "id": "MNXLZRO2PIBULOX2RX56DG25",
            "updated_at": "2020-06-15T20:01:39.58Z",
            "version": 1623784369656,
            "is_deleted": false,
            "present_at_all_locations": true,
            "modifier_data": {
              "name": "Whole Milk",
              "price_money": {
                "amount": 125,
                "currency": "USD"
              },
              "ordinal": 0,
              "modifier_list_id": "ZVSGY6U63IGCZQL4IOPZAKYW"
            }
          },
          {
            "type": "MODIFIER",
            "id": "Q6R5X5VMSZTYVKM37QRHNZWM",
            "updated_at": "2020-06-15T20:01:39.58Z",
            "version": 1623784369656,
            "is_deleted": false,
            "present_at_all_locations": true,
            "modifier_data": {
              "name": "Skim Milk",
              "price_money": {
                "amount": 130,
                "currency": "USD"
              },
             "ordinal": 1,
              "modifier_list_id": "ZVSGY6U63IGCZQL4IOPZAKYW"
            }
          }
        ]
      }
    }
  ]
}

Link to section

Docs

Build a Simple Catalog

On this page

Prerequisites

Information you need

Step 1: Add a coffee item to a catalog

Important

Step 2: Create a CatalogTax object for the coffee drink

Step 3: Create a modifier list to contain two modifiers

Step 4: Apply the modifier list to the coffee item

Step 5: Verify the catalog you just built

See also

On this page