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.

To build this catalog, you will call the UpsertCatalogObject endpoint to 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):

The steps presented here is generally applicable to creating catalog objects of other types except for uploading an image object. For instructions to upload an image to a catalog and attach it to an item, item variation or category, see Create a Catalog Image .

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.

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.

Information you need Permalink Get a link to this section

To use the steps in this topic, you need:

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

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

curl https://connect.squareupsandbox.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.

Because the UpsertCatalogObject endpoint is used to create other catalog objects, the data object you can specify must match the specified type property value. In this example, you must set the item_data property to an appropriate item data object to match the ITEM type. If ITEM_VARIATION is set on type as is shown in the next step, only an appropriate CatalogItemVariation object may be set as the item_variation_data property value. Similarly, to set up a discount to be applied to an order, you must only specify an appropriate CatalogDiscount object on the discount_data field while setting the type value to DISCOUNT.

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.squareupsandbox.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 to which 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 the 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.squareupsandbox.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 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:

curl https://connect.squareupsandbox.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.squareupsandbox.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.squareupsandbox.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"
            }
          }
        ]
      }
    }
  ]
}

Related topics Permalink Get a link to this section