Announcing Item Options for the Catalog API

Previous versions of the Catalog API modeled products for sale as items and item variations. An item represents a product that may be sold while an item variation represents the actual object being sold, typically with distinct name, description, SKU, price, and inventory stock level. Items and their variations are related through references to the item variation from the parent item.

You can now use item options to structure and organize catalog items rather than explicit item variations. For example, a T-shirt with 2 item options, color and size, would automatically generate the associated item option values (e.g., "Small, Red", “Small, Blue”).

What has changed

Item options enables you to structure item variations as a matrix of options instead of a flat ordered list. Items are now associated with a list of item options and each item option defines a list of possible values.

A given item option defines a single dimension of the item variation matrix. For example, consider a specific catalog item, “Tshirt”. A typical set of item options might be (Size, Color), where the values for “Size” are (Small, Medium, Large) and the values for “Color” are (Red, Blue, Yellow). Each item variation must be assigned a Size option and a Color option. And a given combination of Size and Color options can only be assigned to, at most, 1 item variation. In this way, we have organized the fully set of item variations into a virtual Item Option Matrix.

What you need to know

For items that use item options

The name field and ordinal field are now managed at the item option level. Attempting to update the name or ordinal at the item variation level will return an error. The display order for an item variation is determined by the order of the associated item option values. And the display name for an item variation is derived by combining the names of the item option values associated with the item variation.

You can continue to manage other details, including inventory counts and SKU, at the item variation level.

Items that do not use item options

You can continue to manage the name, ordinal, and other details at the item variation level. These items will continue to work the same way.

What to do

You have 3 options, depending on how you want to manage your catalog items.

Option 1: Continue to use your catalog as it currently exists

If your item catalog does not need any structure beyond ordered lists and you do not need to update the name or ordinal, then you can continue to manage metadata for your item variations the same way you always have.

However, if you create new items that use item options or restructure existing items to use item options, you will need to manage the name and ordinal at the item variation level.

Option 2: Keep existing items the same and use item options for new items

If you would like to use item options for some, but not all, of your catalog, you can maintain a combination of items that use the old item/variation structure and items that use item options. But be aware that items using item options cannot be managed the same way as items that use the old item variation model. Your code will need to differentiate between these two types of items. In particular, you need to manage name and ordinal information for your new items at the item option level.

Option 3: Restructure your entire catalog to use item options

If you want to use item options for all of your existing items, you will need to restructure your product catalog:

Use BatchRetrieveCatalogObjects to get the catalog object IDs for the catalog items you need to edit.

Configure new item option objects using the name and ordinal from the existing item variations.

Reference the item option values in the item variations.

Set the name and ordinal for the item variation to be null or blank.

Send a BatchUpsertCatalogObjects request to update your catalog.

STEP 1: Retrieve the item and item variations you want to restructure

For example, suppose you retrieve an item (“T-shirt”) with 3 item variations that represent the sizes “Small”, “Medium”, and “Large” in the color “Red”:

{
  "catalog_object": {
    "type": "ITEM",
    ...
    "item_data": {
      "name": "T-shirt",
      ... 
    }
  }
}

{
  "catalog_object": {
    "type": "ITEM_VARIATION",
    ...
    "item_variation_data": {
      "name": "Small, Red",
      "ordinal": "1"

      ... 
      
    }
  }
}

{
  "catalog_object": {
    "type": "ITEM_VARIATION",
    ...
    "item_variation_data": {
      "name": "Medium, Red",
      "ordinal": "2"

      ... 
      
    }
  }
}

{
  "catalog_object": {
    "type": "ITEM_VARIATION",
    ...
    "item_variation_data": {
      "name": "Large, Red",
      "ordinal": "3"

      ... 
      
    }
  }
}

STEP 2: Create item options

Use the following cURL command to create 2 new item options. The BatchUpsertCatalogObjectsResponse will return item option value IDs that you can reference in your item variations in the next step.

curl -X POST \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-H 'Square-Version: 2019-07-24' \
-d '{
  "idempotency_key": "b134aa8a-10ef-4eb8-886c-b16169ee5fd4",
  "batches": [
    {
      "objects": [
        {
          "id": "#shirt-size-item-option",
          "type": "ITEM_OPTION",
          "item_option_data":{
            "name": "T-Shirt Size",
            "display_name": "Size",
            "description": "Size for T-Shirts",
            "values":[
              {
                "id": "#shirt-size-small",
                "type": "ITEM_OPTION_VAL",
                "item_option_value_data":{
                  "name":"S",
                  "display_name": "Small"
                }
              },
              {
                "id": "#shirt-size-medium",
                "type": "ITEM_OPTION_VAL",
                "item_option_value_data":{
                  "name":"M",
                  "display_name": "Medium"
                }
              },
              {
                "id": "#shirt-size-large",
                "type": "ITEM_OPTION_VAL",
                "item_option_value_data":{
                  "name":"L",
                  "display_name": "Large"
                }
              }
            ]
          }
        },
        {
          "id": "#shirt-color-item-option",
          "type": "ITEM_OPTION",
          "item_option_data":{
            "name": "T-Shirt Color",
            "display_name": "Color",
            "description": "Color for T-shirts",
            "values":[
              {
                "id": "#shirt-color-red",
                "type": "ITEM_OPTION_VAL",
                "item_option_value_data":{
                  "name":"R",
                  "display_name": "Red"
                }
              },
              {
                "id": "#shirt-color-blue",
                "type": "ITEM_OPTION_VAL",
                "item_option_value_data":{
                  "name":"B",
                  "display_name": "Blue"
                }
              }
            ]
          }
        }
      ]
    }
  ]
}' \
'https://connect.squareup.com/v2/catalog/batch-upsert'

STEP 3: Associate item variation with item option values

Use the following curl command to associate your item variations with these items, and update the name and ordinal fields to be null:

curl -X POST \
-H 'Accept: application/json' \
-H 'Authorization: Bearer sq0ats-QNM0Z-rD4SBXGYunueACWw' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-H 'Square-Version: 2019-07-24' \
-d '{
  "idempotency_key": "377814e3-8e12-4f9b-bf34-c9b5489a6cb9",
  "batches": [
    {
      "objects": [
        {
          "type": "ITEM",
          "id": "YBGUJQU6DFJG7TLVGZ7QHCKG",
          "updated_at": "2019-07-19T16:53:24.304Z",
          "version": 1563555204304,
          "is_deleted": false,
          "present_at_all_locations": true,
          "item_data": {
            "name": "T shirt",
            "visibility": "PRIVATE",
            "category_id": "FRZP2FQ2GTR76CNAVIKQ35EF",
            "item_options": [
              {
                "item_option_id": "SIZE_OPTION_ID"
              },
              {
                "item_option_id": "COLOR_OPTION_ID"
              }
            ],
            "product_type": "REGULAR",
            "skip_modifier_screen": false,
            "variations": [
              {
                "type": "ITEM_VARIATION",
                "id": "SMALL_RED_ID",
                "updated_at": "2019-07-19T16:53:24.304Z",
                "version": 1563555204304,
                "is_deleted": false,
                "present_at_all_locations": true,
                "item_variation_data": {
                  "item_id": "TSHIRT_ITEM_ID",
                  "name": null,
                  "sku": "",
                  "ordinal": null,
                  "pricing_type": "FIXED_PRICING",
                  "price_money": {
                    "amount": 500,
                    "currency": "USD"
                  },
                  "item_option_values": [
                    {
                      "item_option_id": "SIZE_OPTION_ID",
                      "item_option_value_id": "MEDIUM_OPTION_VALUE_ID"
                    },
                    {
                      "item_option_id": "COLOR_OPTION_ID",
                      "item_option_value_id": "RED_OPTION_VALUE_ID"
                    }
                  ]
                }
              },
              {
                "type": "ITEM_VARIATION",
                "id": "MEDIUM_RED_ID",
                "updated_at": "2019-07-19T16:53:24.304Z",
                "version": 1563555204304,
                "is_deleted": false,
                "present_at_all_locations": true,
                "item_variation_data": {
                  "item_id": "TSHIRT_ITEM_ID",
                  "name": null,
                  "sku": "",
                  "ordinal": null,
                  "pricing_type": "FIXED_PRICING",
                  "price_money": {
                    "amount": 500,
                    "currency": "USD"
                  },
                  "item_option_values": [
                    {
                      "item_option_id": "SIZE_OPTION_ID",
                      "item_option_value_id": "LARGE_OPTION_VALUE_ID"
                    },
                    {
                      "item_option_id": "COLOR_OPTION_ID",
                      "item_option_value_id": "RED_OPTION_VALUE_ID"
                    }
                  ]
                }
              },
              {
                "type": "ITEM_VARIATION",
                "id": "LARGE_RED_ID",
                "updated_at": "2019-07-19T16:53:24.304Z",
                "version": 1563555204304,
                "is_deleted": false,
                "present_at_all_locations": true,
                "item_variation_data": {
                  "item_id": "TSHIRT_ITEM_ID",
                  "name": null,
                  "sku": "",
                  "ordinal": null,
                  "pricing_type": "FIXED_PRICING",
                  "price_money": {
                    "amount": 500,
                    "currency": "USD"
                  },
                  "item_option_values": [
                    {
                      "item_option_id": "SIZE_OPTION_ID",
                      "item_option_value_id": "LARGE_OPTION_VALUE_ID"
                    },
                    {
                      "item_option_id": "COLOR_OPTION_ID",
                      "item_option_value_id": "RED_OPTION_VALUE_ID"
                    }
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  ]
}' \
'https://connect.squareup.com/v2/catalog/batch-upsert'

If you would like to see Item Options displayed your Square Dashboard today: create a separate account specifically for testing item options, and then contact [email protected] to get Item Options for your test account.