Beta Release
This is pre-release documentation for an API in public beta and is subject to change.
Catalog API

Item Options Migration

Learn more about how to restructure your catalog to use item options.

Catalog API

Introduction
Permalink Get a link to this section

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.

Modeling the relationship of items and item variations as parent/child references results in a flat list of item variations that must account for all possible combinations. Forcing item variations into a flat list limits how Square products and SDKs can display item variations during the checkout flow. diagram-catalog-3

What has changed
Permalink Get a link to this section

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.

diagram-catalog-4@2x

What you need to know
Permalink Get a link to this section

For items that use item options
Permalink Get a link to this section

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
Permalink Get a link to this section

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
Permalink Get a link to this section

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
Permalink Get a link to this section

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
Permalink Get a link to this section

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
Permalink Get a link to this section

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

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

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

  3. Reference the item option values in the item variations.

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

  5. Send a BatchUpsertCatalogObjects request to update your catalog.

Step 1: Retrieve the item and item variations you want to restructure
Permalink Get a link to this section

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
Permalink Get a link to this section

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
Permalink Get a link to this section

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 ACCESS_TOKEN' \
-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'