Catalog API

Build a Simple Catalog

In this guide, you 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 options.

To build this catalog, you create the following catalog objects to represent the for-sale item (Coffee), two variations (Small Coffee or Large Coffee) of the sale item, and two optional modifications (with Skim Milk or Whole Milk):

Prerequisites
Permalink Get a link to this section

  • You have a Square account enabled for payment processing. If you have not enabled payment processing on your account (or you are not sure), visit squareup.com/activate.

We also assume the following:

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

Information you need
Permalink Get a link to this section

To use the steps in this guide, you need the following information:

  • A valid access token. You should test with Sandbox credentials whenever possible. For more information, see Square API Access Tokens.

Step 1: Add a coffee item to a catalog
Permalink Get a link to this section

To add a CatalogItem object to a catalog, call the Upsert Catalog object endpoint as shown in the following example:

curl https://connect.squareup.com/v2/catalog/object \
  -X POST \
  -H 'Square-Version: 2020-05-28' \
  -H 'Authorization: Bearer {SQUARE_ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "2363479e-ac49-4a1d-9575-ed7fe5858e08",
    "object": {
      "id": "#coffee",
      "type": "ITEM",
      "item_data": {
        "abbreviation": "Co",
        "description": "Coffee Drink",
        "name": "Coffee"
      }
    }
  }'

The #coffee ID is a temporary ID, serving as a placeholder for the permanent ID generated by the Square API 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. In a separate request, you must use the permanent ID value to reference this object.

If the request is successful, you get a response similar to the following:

{
  "catalog_object": {
    "type": "ITEM",
    "id": "QRIAAXI7PEBG6WDEX6DG6WHL",
    "updated_at": "2020-05-29T19:52:56.399Z",
    "version": 1590781976399,
    "is_deleted": false,
    "present_at_all_locations": true,
    "item_data": {
      "name": "Coffee",
      "description": "Coffee Drink",
      "abbreviation": "Co",
      "product_type": "REGULAR"
    }
  },
  "id_mappings": [
    {
      "client_object_id": "#coffee",
      "object_id": "QRIAAXI7PEBG6WDEX6DG6WHL"
    }
  ]
}

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 this object by its object_id value.

Step 2: Create two CatalogItemVariation objects for the size variations
Permalink Get a link to this section

To create a Small variation for the Coffee item, follow the example to call the UpsertCatalogOjbect endpoint:

curl https://connect.squareup.com/v2/catalog/object \
  -X POST \
  -H 'Square-Version: 2020-05-28' \
  -H 'Authorization: Bearer {SQUARE_ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "4066b524-c872-4d9a-a0b3-474c901f1234",
    "object": {
      "id": "#small_coffee",
      "type": "ITEM_VARIATION",
      "item_variation_data": {
        "name": "Small",
        "price_money": {
          "amount": 300,
          "currency": "USD"
        },
        "pricing_type": "FIXED_PRICING",
        "item_id": "QRIAAXI7PEBG6WDEX6DG6WHL"
      }
    }
  }'

You need to set item_id as the permanent ID of the item this variation applies. As shown, #small_coffee is a temporary ID value of this to-be-created CatalogItemVariation object.

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

{
  "catalog_object": {
    "type": "ITEM_VARIATION",
    "id": "LBHSVD65G6MXCNYV2AP2TYPP",
    "updated_at": "2020-05-29T20:38:28.304Z",
    "version": 1590784708304,
    "is_deleted": false,
    "present_at_all_locations": true,
    "item_variation_data": {
      "item_id": "QRIAAXI7PEBG6WDEX6DG6WHL",
      "name": "Small",
      "pricing_type": "FIXED_PRICING",
      "price_money": {
        "amount": 300,
        "currency": "USD"
      }
    }
  },
  "id_mappings": [
    {
      "client_object_id": "#small_coffee",
      "object_id": "LBHSVD65G6MXCNYV2AP2TYPP"
    }
  ]
}

To create the Large size variation for Coffee item, you repeat the previous request with the following payload:

{
    "idempotency_key": "617ad73a-6a6e-4fd9-a13e-362fdee79b11",
    "object": {
      "id": "#large_coffee",
      "type": "ITEM_VARIATION",
      "item_variation_data": {
        "name": "Large",
        "price_money": {
          "amount": 350,
          "currency": "USD"
        },
        "pricing_type": "FIXED_PRICING",
        "item_id": "QRIAAXI7PEBG6WDEX6DG6WHL"
      }
    }
  }

Make sure you assign the idempotency_key field a unique value that has not been used in the session. Otherwise, the request fails.

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

{
  "catalog_object": {
    "type": "ITEM_VARIATION",
    "id": "AH2XNLUYOV4RCVBSJX66F7RV",
    "updated_at": "2020-05-29T20:58:34.455Z",
    "version": 1590785914455,
    "is_deleted": false,
    "present_at_all_locations": true,
    "item_variation_data": {
      "item_id": "QRIAAXI7PEBG6WDEX6DG6WHL",
      "name": "Large",
      "pricing_type": "FIXED_PRICING",
      "price_money": {
        "amount": 350,
        "currency": "USD"
      }
    }
  },
  "id_mappings": [
    {
      "client_object_id": "#large_coffee",
      "object_id": "AH2XNLUYOV4RCVBSJX66F7RV"
    }
  ]
}

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

curl https://connect.squareup.com/v2/catalog/object \
  -X POST \
  -H 'Square-Version: 2020-05-28' \
  -H 'Authorization: Bearer {SQUARE_ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
  "catalog_object": {
    "type": "ITEM",
    "id": "#coffee",
    "is_deleted": false,
    "present_at_all_locations": true,
    "item_data": {
      "name": "Coffee",
      "description": "Coffee Drink",
      "abbreviation": "Co",
      "product_type": "REGULAR",
      "variations":[
        {
          "id": "#small_coffee",
          "type": "ITEM_VARIATION",
          "item_variation_data": {
            "name": "Small",
            "price_money": {
              "amount": 300,
              "currency": "USD"
            },
            "pricing_type": "FIXED_PRICING",
            "item_id": "#coffee"
          }
        },
        {
          "id": "#large_coffee",
          "type": "ITEM_VARIATION",
          "item_variation_data": {
            "name": "Large",
            "price_money": {
              "amount": 350,
              "currency": "USD"
            },
            "pricing_type": "FIXED_PRICING",
            "item_id": "#coffee"
          }
        }
      ]
    }
  }
  ]
}  

In the batch request, a previously defined object within the request body is referenced by its temporary ID (#{id_string}) when it is called in another object in the same request. For example, the Small or Large object of the ITEM_VARIATION type references the Coffee object of the ITEM type by the Coffee object's temporary ID of #coffee.

Step 3: Create a modifier list to contain two modifiers
Permalink Get a link to this section

To enable sellers to offer choices of Skim Milk and Whole Milk, 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:

curl https://connect.squareup.com/v2/catalog/object \
  -X POST \
  -H 'Square-Version: 2020-05-28' \
  -H 'Authorization: Bearer {SQUARE_ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "78277c13-aad4-4eff-9e16-69a56eeaafe1",
    "object": {
      "id": "#modifier_list",
      "type": "MODIFIER_LIST",
      "modifier_list_data": {
        "name": "Milk Options",
        "modifiers": [
          {
            "id": "#whole_milk",
            "type": "MODIFIER",
            "modifier_data": {
              "modifier_list_id": "#modifier_list",
              "name": "Whole Milk",
              "price_money": {
                "amount": 125,
                "currency": "USD"
              }
            }
          },
          {
            "id": "#skim_milk",
            "type": "MODIFIER",
            "modifier_data": {
              "modifier_list_id": "#modifier_list",
              "name": "Skim Milk",
              "price_money": {
                "amount": 130,
                "currency": "USD"
              }
            }
          }
        ]
      }
    }
  }'

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-05-29T21:38:39.58Z",
    "version": 1590788319580,
    "is_deleted": false,
    "present_at_all_locations": true,
    "modifier_list_data": {
      "name": "Milk Options",
      "modifiers": [
        {
          "type": "MODIFIER",
          "id": "MNXLZRO2PIBULOX2RX56DG25",
          "updated_at": "2020-05-29T21:38:39.58Z",
          "version": 1590788319580,
          "is_deleted": false,
          "present_at_all_locations": true,
          "modifier_data": {
            "name": "Whole Milk",
            "price_money": {
              "amount": 125,
              "currency": "USD"
            },
            "on_by_default": false,
            "ordinal": 0,
            "modifier_list_id": "ZVSGY6U63IGCZQL4IOPZAKYW"
          }
        },
        {
          "type": "MODIFIER",
          "id": "Q6R5X5VMSZTYVKM37QRHNZWM",
          "updated_at": "2020-05-29T21:38:39.58Z",
          "version": 1590788319580,
          "is_deleted": false,
          "present_at_all_locations": true,
          "modifier_data": {
            "name": "Skim Milk",
            "price_money": {
              "amount": 130,
              "currency": "USD"
            },
            "on_by_default": false,
            "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.

Step 4: Apply the modifier list to the coffee item
Permalink Get a link to this section

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

curl https://connect.squareup.com/v2/catalog/update-item-modifier-lists \
  -X POST \
  -H 'Square-Version: 2020-05-28' \
  -H 'Authorization: Bearer {SQUARE_ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "item_ids": [
      "QRIAAXI7PEBG6WDEX6DG6WHL"
    ],
    "modifier_lists_to_enable": [
      "ZVSGY6U63IGCZQL4IOPZAKYW"
    ]
  }'

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

{
  "updated_at": "2020-05-29T22:25:47.216Z"
}

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.

Step 5: Verify the catalog you just built
Permalink Get a link to this section

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:

curl https://connect.squareup.com/v2/catalog/list \
  -H 'Square-Version: 2020-05-28' \
  -H 'Authorization: Bearer {SQUARE_ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

In response, the payload contains the catalog objects:

{
  "objects": [
    {
      "type": "ITEM",
      "id": "QRIAAXI7PEBG6WDEX6DG6WHL",
      "updated_at": "2020-05-29T22:25:47.216Z",
      "version": 1590791147216,
      "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": "AH2XNLUYOV4RCVBSJX66F7RV",
            "updated_at": "2020-05-29T20:58:34.455Z",
            "version": 1590785914455,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_variation_data": {
              "item_id": "QRIAAXI7PEBG6WDEX6DG6WHL",
              "name": "Large",
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 350,
                "currency": "USD"
              }
            }
          },
          {
            "type": "ITEM_VARIATION",
            "id": "LBHSVD65G6MXCNYV2AP2TYPP",
            "updated_at": "2020-05-29T20:38:28.304Z",
            "version": 1590784708304,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_variation_data": {
              "item_id": "QRIAAXI7PEBG6WDEX6DG6WHL",
              "name": "Small",
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 300,
                "currency": "USD"
              }
            }
          }
        ],
        "product_type": "REGULAR"
      }
    },
    {
      "type": "MODIFIER_LIST",
      "id": "ZVSGY6U63IGCZQL4IOPZAKYW",
      "updated_at": "2020-05-29T21:38:39.58Z",
      "version": 1590788319580,
      "is_deleted": false,
      "present_at_all_locations": true,
      "modifier_list_data": {
        "name": "Milk Options",
        "modifiers": [
          {
            "type": "MODIFIER",
            "id": "MNXLZRO2PIBULOX2RX56DG25",
            "updated_at": "2020-05-29T21:38:39.58Z",
            "version": 1590788319580,
            "is_deleted": false,
            "present_at_all_locations": true,
            "modifier_data": {
              "name": "Whole Milk",
              "price_money": {
                "amount": 125,
                "currency": "USD"
              },
              "on_by_default": false,
              "ordinal": 0,
              "modifier_list_id": "ZVSGY6U63IGCZQL4IOPZAKYW"
            }
          },
          {
            "type": "MODIFIER",
            "id": "Q6R5X5VMSZTYVKM37QRHNZWM",
            "updated_at": "2020-05-29T21:38:39.58Z",
            "version": 1590788319580,
            "is_deleted": false,
            "present_at_all_locations": true,
            "modifier_data": {
              "name": "Skim Milk",
              "price_money": {
                "amount": 130,
                "currency": "USD"
              },
              "on_by_default": false,
              "ordinal": 1,
              "modifier_list_id": "ZVSGY6U63IGCZQL4IOPZAKYW"
            }
          }
        ]
      }
    }
  ]
}

Next step
Permalink Get a link to this section