Catalog API

Use Item Options to Manage Item Variations

Item variations are chargeable items related by certain variables. For example, a shirt is a product that can be represented by an item. However, a small red shirt is a chargeable product item with specified variations in size and color. The same is true for a large blue shirt. A seller can sell a shirt, which is represented by an item in the Catalog API, but the seller can only charge customers for a small red shirt or a large blue shirt, which is represented as an item variation in the API.

However, in an item variation, multiple parameters are combined into a single variable. This forces a related item variations into a flat ordered list, making it difficult to retrieve the item variations by a constituent variable, which is akin to random access to the targeted item variations.

You can use item options to manage related item variations by their constituent variables individually, which provides flexible and streamlined organization and retrieval of these objects. In this topic, you learn details about item variations and item options and how to restructure your catalog to use item options to manage item variations.

Item variations
Item options
Manage item variations with or without item options
Migrate item variations to use item options

Link to section
Item variations

In previous versions of the Square catalog, products for sale are modeled as items and item variations. An item represents a type of product that can be sold while an item variation represents a particular object being sold. Typically, item variations are related items that can vary, for example, in name, description, SKU, price, inventory stock level, or any combination of such. Because prices can be set only on item variations, chargeable entries in an order must be item variations of the CatalogItemVariation type.

Each entry of the variations list is an item variation of either a simple one-dimensional parameter or a composite of multiple parameters as described in the preceding example. Simple item variations are powerful and easy to use, whereas composite item variations collapse multiple choices into a single choice and are awkward or unsuitable for display during the checkout flow.

A diagram showing an item with simple item variations without item options.

Link to section
Create item variations related by size and color without item options

To add item variations to a catalog, you create a (CatalogItem) instance with a list of CatalogItemVariation instances nested within the item through the variations attribute on the CatalogItem object.

Link to section
Request

Upsert Catalog Object

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91

curl https://connect.squareupsandbox.com/v2/catalog/object \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "object": {
      "id": "#shirt",
      "type": "ITEM",
      "item_data": {
        "description": "Shirt",
        "name": "Shirt",
        "product_type": "REGULAR",
        "variations": [
          {
            "id": "#shirt_small_red",
            "type": "ITEM_VARIATION",
            "item_variation_data": {
              "name": "Small red shirt",
              "price_money": {
                "amount": 2500,
                "currency": "USD"
              },
              "pricing_type": "FIXED_PRICING"
            }
          },
          {
            "id": "#shirt_medium_red",
            "type": "ITEM_VARIATION",
            "item_variation_data": {
              "name": "Medium red shirt",
              "price_money": {
                "amount": 3000,
                "currency": "USD"
              },
              "pricing_type": "FIXED_PRICING"
            }
          },
          {
            "id": "#shirt_large_red",
            "type": "ITEM_VARIATION",
            "item_variation_data": {
              "name": "Large red shirt",
              "price_money": {
                "amount": 3500,
                "currency": "USD"
              },
              "pricing_type": "FIXED_PRICING"
            }
          },
          {
            "id": "#shirt_small_blue",
            "type": "ITEM_VARIATION",
            "item_variation_data": {
              "name": "Small blue shirt",
              "price_money": {
                "amount": 2500,
                "currency": "USD"
              },
              "pricing_type": "FIXED_PRICING"
            }
          },
          {
            "id": "#shirt_medium_blue",
            "type": "ITEM_VARIATION",
            "item_variation_data": {
              "name": "Medium blue shirt",
              "price_money": {
                "amount": 3000,
                "currency": "USD"
              },
              "pricing_type": "FIXED_PRICING"
            }
          },
          {
            "id": "#shirt_large_blue",
            "type": "ITEM_VARIATION",
            "item_variation_data": {
              "name": "Large blue shirt",
              "price_money": {
                "amount": 3500,
                "currency": "USD"
              },
              "pricing_type": "FIXED_PRICING"
            }
          }
        ]
      }
    }
  }'

Link to section
Response

The request results in a CatalogItem instance with six CatalogItemVariation instances nested within.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155

{
  "catalog_object": {
    "type": "ITEM",
    "id": "3RJ4KVW64QXHXYDJ5CS6J4LE",
    "updated_at": "2020-10-17T00:08:15.13Z",
    "version": 1602893295130,
    "is_deleted": false,
    "present_at_all_locations": true,
    "item_data": {
      "name": "Shirt",
      "description": "Shirt",
      "variations": [
        {
          "type": "ITEM_VARIATION",
          "id": "F3P54C436KUEUGMRCUFYBEIZ",
          "updated_at": "2020-10-17T00:08:15.13Z",
          "version": 1602893295130,
          "is_deleted": false,
          "present_at_all_locations": true,
          "item_variation_data": {
            "item_id": "3RJ4KVW64QXHXYDJ5CS6J4LE",
            "name": "Small red shirt",
            "ordinal": 0,
            "pricing_type": "FIXED_PRICING",
            "price_money": {
              "amount": 2500,
              "currency": "USD"
            }
          }
        },
        {
          "type": "ITEM_VARIATION",
          "id": "IJBAQDICELYUAUTHM352X3AI",
          "updated_at": "2020-10-17T00:08:15.13Z",
          "version": 1602893295130,
          "is_deleted": false,
          "present_at_all_locations": true,
          "item_variation_data": {
            "item_id": "3RJ4KVW64QXHXYDJ5CS6J4LE",
            "name": "Medium red shirt",
            "ordinal": 1,
            "pricing_type": "FIXED_PRICING",
            "price_money": {
              "amount": 3000,
              "currency": "USD"
            }
          }
        },
        {
          "type": "ITEM_VARIATION",
          "id": "5JMHD2SBPVG3A7ZFN5HDXSY6",
          "updated_at": "2020-10-17T00:08:15.13Z",
          "version": 1602893295130,
          "is_deleted": false,
          "present_at_all_locations": true,
          "item_variation_data": {
            "item_id": "3RJ4KVW64QXHXYDJ5CS6J4LE",
            "name": "Large red shirt",
            "ordinal": 2,
            "pricing_type": "FIXED_PRICING",
            "price_money": {
              "amount": 3500,
              "currency": "USD"
            }
          }
        },
        {
          "type": "ITEM_VARIATION",
          "id": "FQZGFI5ZQZY4RYK3H5X3QG2X",
          "updated_at": "2020-10-17T00:08:15.13Z",
          "version": 1602893295130,
          "is_deleted": false,
          "present_at_all_locations": true,
          "item_variation_data": {
            "item_id": "3RJ4KVW64QXHXYDJ5CS6J4LE",
            "name": "Small blue shirt",
            "ordinal": 3,
            "pricing_type": "FIXED_PRICING",
            "price_money": {
              "amount": 2500,
              "currency": "USD"
            }
          }
        },
        {
          "type": "ITEM_VARIATION",
          "id": "6F4K33KPNUVDWKZ43KUIFH6K",
          "updated_at": "2020-10-17T00:08:15.13Z",
          "version": 1602893295130,
          "is_deleted": false,
          "present_at_all_locations": true,
          "item_variation_data": {
            "item_id": "3RJ4KVW64QXHXYDJ5CS6J4LE",
            "name": "Medium blue shirt",
            "ordinal": 4,
            "pricing_type": "FIXED_PRICING",
            "price_money": {
              "amount": 3000,
              "currency": "USD"
            }
          }
        },
        {
          "type": "ITEM_VARIATION",
          "id": "H6QGZ6Q3XBEIL672DZYQW5SH",
          "updated_at": "2020-10-17T00:08:15.13Z",
          "version": 1602893295130,
          "is_deleted": false,
          "present_at_all_locations": true,
          "item_variation_data": {
            "item_id": "3RJ4KVW64QXHXYDJ5CS6J4LE",
            "name": "Large blue shirt",
            "ordinal": 5,
            "pricing_type": "FIXED_PRICING",
            "price_money": {
              "amount": 3500,
              "currency": "USD"
            }
          }
        }
      ],
      "product_type": "REGULAR"
    }
  },
  "id_mappings": [
    {
      "client_object_id": "#shirt",
      "object_id": "3RJ4KVW64QXHXYDJ5CS6J4LE"
    },
    {
      "client_object_id": "#shirt_small_red",
      "object_id": "F3P54C436KUEUGMRCUFYBEIZ"
    },
    {
      "client_object_id": "#shirt_medium_red",
      "object_id": "IJBAQDICELYUAUTHM352X3AI"
    },
    {
      "client_object_id": "#shirt_large_red",
      "object_id": "5JMHD2SBPVG3A7ZFN5HDXSY6"
    },
    {
      "client_object_id": "#shirt_small_blue",
      "object_id": "FQZGFI5ZQZY4RYK3H5X3QG2X"
    },
    {
      "client_object_id": "#shirt_medium_blue",
      "object_id": "6F4K33KPNUVDWKZ43KUIFH6K"
    },
    {
      "client_object_id": "#shirt_large_blue",
      "object_id": "H6QGZ6Q3XBEIL672DZYQW5SH"
    }
  ]
}

Link to section
Item options

Item options let you structure item variations as a matrix of options instead of a flat ordered list. When a variation takes multiple parameters, you first create a CatalogItemOption instance for the variation parameter. Items are now associated with a list of item options and each item option defines a list of possible values.

Instead of using the variation's name attribute as the indexing parameter, you attach the list of the item option values to the item variation object through the item_option_values attribute. Item variations can then be indexed over the attached item option values. If the item_option_values list contains a single option, the resulting item variation is an order list. If the item_option_values list contains two options, the resulting item variations form a matrix. More generally, if the item_option_values list contains n options, the resulting item variation forms a tensor of rank n.

A given item option defines a single dimension of the item variation matrix. For example, consider a specific catalog item named T-shirt. A typical set of item options might be Size and Color, where the values for Size are Small, Medium, and Large and the values for Color are Red, Blue, and Yellow. Each item variation must be assigned a Size option and a Color option. Also, a given combination of Size and Color options can only be assigned to, at most, one item variation. In this way, you can organize the full set of item variations into a virtual item option matrix.

A diagram showing an item with composite item variations with item options.

Link to section
Create item variations related by size and color with item options

The following cURL example illustrates how to create item options similar to the preceding example.

Programmatically, the call proceeds by calling the BatchUpsertCatalogObject endpoint, first creating two CatalogItemOption objects and then creating a CatalogItem instance with six nested CatalogItemVariation objects. Attached to each CatalogItemVariation object are two item option values defining the supported colors (red and blue) and sizes (small, medium, and large).

Link to section
Request

Batch Upsert Catalog Objects

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211

curl https://connect.squareupsandbox.com/v2/catalog/batch-upsert \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "batches": [
      {
        "objects": [
          {
            "id": "#item_option_color",
            "type": "ITEM_OPTION",
            "item_option_data": {
              "name": "COLOR_OPTIONS",
              "values": [
                {
                  "id": "#item_option_value_color_red",
                  "type": "ITEM_OPTION_VAL",
                  "item_option_value_data": {
                    "name": "RED"
                  }
                },
                {
                  "id": "#item_option_value_color_blue",
                  "type": "ITEM_OPTION_VAL",
                  "item_option_value_data": {
                    "name": "Blue"
                  }
                }
              ]
            }
          },
          {
            "id": "#item_option_size",
            "type": "ITEM_OPTION",
            "item_option_data": {
              "name": "SIZE_OPTIONS",
              "values": [
                {
                  "id": "#item_option_value_size_small",
                  "type": "ITEM_OPTION_VAL",
                  "item_option_value_data": {
                    "name": "Small"
                  }
                },
                {
                  "id": "#item_option_value_size_medium",
                  "type": "ITEM_OPTION_VAL",
                  "item_option_value_data": {
                    "name": "Medium"
                  }
                },
                {
                  "id": "#item_option_value_size_large",
                  "type": "ITEM_OPTION_VAL",
                  "item_option_value_data": {
                    "name": "Large"
                  }
                }
              ]
            }
          },
          {
            "id": "#item",
            "type": "ITEM",
            "item_data": {
              "name": "Shirt",
              "product_type": "REGULAR",
              "item_options": [
                {
                  "item_option_id": "#item_option_size"
                },
                {
                  "item_option_id": "#item_option_color"
                }
              ],
              "variations": [
                {
                  "id": "#item_variation_small_red",
                  "type": "ITEM_VARIATION",
                  "item_variation_data": {
                    "item_option_values": [
                      {
                        "item_option_id": "#item_option_size",
                        "item_option_value_id": "#item_option_value_size_small"
                      },
                      {
                        "item_option_id": "#item_option_color",
                        "item_option_value_id": "#item_option_value_color_red"
                      }
                    ],
                    "price_money": {
                      "amount": 2500,
                      "currency": "USD"
                    },
                    "pricing_type": "FIXED_PRICING"
                  }
                },
                {
                  "id": "#item_variation_medium_red",
                  "type": "ITEM_VARIATION",
                  "item_variation_data": {
                    "item_option_values": [
                      {
                        "item_option_id": "#item_option_size",
                        "item_option_value_id": "#item_option_value_size_medium"
                      },
                      {
                        "item_option_id": "#item_option_color",
                        "item_option_value_id": "#item_option_value_color_red"
                      }
                    ],
                    "price_money": {
                      "amount": 3000,
                      "currency": "USD"
                    },
                    "pricing_type": "FIXED_PRICING"
                  }
                },
                {
                  "id": "#item_variation_large_red",
                  "type": "ITEM_VARIATION",
                  "item_variation_data": {
                    "item_option_values": [
                      {
                        "item_option_id": "#item_option_size",
                        "item_option_value_id": "#item_option_value_size_large"
                      },
                      {
                        "item_option_id": "#item_option_color",
                        "item_option_value_id": "#item_option_value_color_red"
                      }
                    ],
                    "price_money": {
                      "amount": 3500,
                      "currency": "USD"
                    },
                    "pricing_type": "FIXED_PRICING"
                  }
                },
                {
                  "id": "#item_variation_small_blue",
                  "type": "ITEM_VARIATION",
                  "item_variation_data": {
                    "item_option_values": [
                      {
                        "item_option_id": "#item_option_size",
                        "item_option_value_id": "#item_option_value_size_small"
                      },
                      {
                        "item_option_id": "#item_option_color",
                        "item_option_value_id": "#item_option_value_color_blue"
                      }
                    ],
                    "price_money": {
                      "amount": 2500,
                      "currency": "USD"
                    },
                    "pricing_type": "FIXED_PRICING"
                  }
                },
                {
                  "id": "#item_variation_medium_blue",
                  "type": "ITEM_VARIATION",
                  "item_variation_data": {
                    "item_option_values": [
                      {
                        "item_option_id": "#item_option_size",
                        "item_option_value_id": "#item_option_value_size_medium"
                      },
                      {
                        "item_option_id": "#item_option_color",
                        "item_option_value_id": "#item_option_value_color_blue"
                      }
                    ],
                    "price_money": {
                      "amount": 3000,
                      "currency": "USD"
                    },
                    "pricing_type": "FIXED_PRICING"
                  }
                },
                {
                  "id": "#item_variation_large_blue",
                  "type": "ITEM_VARIATION",
                  "item_variation_data": {
                    "item_option_values": [
                      {
                        "item_option_id": "#item_option_size",
                        "item_option_value_id": "#item_option_value_size_large"
                      },
                      {
                        "item_option_id": "#item_option_color",
                        "item_option_value_id": "#item_option_value_color_blue"
                      }
                    ],
                    "price_money": {
                      "amount": 3500,
                      "currency": "USD"
                    },
                    "pricing_type": "FIXED_PRICING"
                  }
                }
              ]
            }
          }
        ]
      }
    ]
  }'

Notice how item option values are attached to an item variation by referencing relevant item option IDs and item option value IDs in the item_option_values attribute of an item variation.

Link to section
Response

The request results in the creation of:

Two item options (of CatalogItemOption): one for size and one for color.
One item (of CatalogItem).
Six item variations (of CatalogItemVariation) nested within the item. Each item variation references the size and color options by the corresponding item option value IDs defined in the two item option objects, respectively.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343

{
  "objects": [
    {
      "type": "ITEM_OPTION",
      "id": "GYWZZUMPQGBNMBANC32WWSWC",
      "updated_at": "2020-10-17T04:44:20.494Z",
      "version": 1602909860494,
      "is_deleted": false,
      "present_at_all_locations": true,
      "item_option_data": {
        "name": "COLOR_OPTIONS",
        "values": [
          {
            "type": "ITEM_OPTION_VAL",
            "id": "O7XQMPXSMFSGUSATAGARGX3E",
            "updated_at": "2020-10-17T04:44:20.494Z",
            "version": 1602909860494,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_option_value_data": {
              "item_option_id": "GYWZZUMPQGBNMBANC32WWSWC",
              "name": "RED",
              "ordinal": 0
            }
          },
          {
            "type": "ITEM_OPTION_VAL",
            "id": "W55IT3LUEQI62LTLXOPLXYEL",
            "updated_at": "2020-10-17T04:44:20.494Z",
            "version": 1602909860494,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_option_value_data": {
              "item_option_id": "GYWZZUMPQGBNMBANC32WWSWC",
              "name": "Blue",
              "ordinal": 1
            }
          }
        ]
      }
    },
    {
      "type": "ITEM_OPTION",
      "id": "WUHPNVNVCW2KBXZ36GT2BNZH",
      "updated_at": "2020-10-17T04:44:20.494Z",
      "version": 1602909860494,
      "is_deleted": false,
      "present_at_all_locations": true,
      "item_option_data": {
        "name": "SIZE_OPTIONS",
        "values": [
          {
            "type": "ITEM_OPTION_VAL",
            "id": "O55AQ6U4HFWDAIPHFHURPMEA",
            "updated_at": "2020-10-17T04:44:20.494Z",
            "version": 1602909860494,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_option_value_data": {
              "item_option_id": "WUHPNVNVCW2KBXZ36GT2BNZH",
              "name": "Small",
              "ordinal": 0
            }
          },
          {
            "type": "ITEM_OPTION_VAL",
            "id": "RJI7UGDMDVOHBEQJSASTWOOJ",
            "updated_at": "2020-10-17T04:44:20.494Z",
            "version": 1602909860494,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_option_value_data": {
              "item_option_id": "WUHPNVNVCW2KBXZ36GT2BNZH",
              "name": "Medium",
              "ordinal": 1
            }
          },
          {
            "type": "ITEM_OPTION_VAL",
            "id": "56QF4FR2BC2D67K4QJ2U2KYC",
            "updated_at": "2020-10-17T04:44:20.494Z",
            "version": 1602909860494,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_option_value_data": {
              "item_option_id": "WUHPNVNVCW2KBXZ36GT2BNZH",
              "name": "Large",
              "ordinal": 2
            }
          }
        ]
      }
    },
    {
      "type": "ITEM",
      "id": "EQVBSUZZ65RO2WWPFU6PLYWU",
      "updated_at": "2020-10-17T04:44:20.494Z",
      "version": 1602909860494,
      "is_deleted": false,
      "present_at_all_locations": true,
      "item_data": {
        "name": "Shirt",
        "variations": [
          {
            "type": "ITEM_VARIATION",
            "id": "6PRFCYBKD7QNDERVZP5FBDL7",
            "updated_at": "2020-10-17T04:44:20.494Z",
            "version": 1602909860494,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_variation_data": {
              "item_id": "EQVBSUZZ65RO2WWPFU6PLYWU",
              "name": "Small, RED",
              "ordinal": 0,
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 2500,
                "currency": "USD"
              },
              "item_option_values": [
                {
                  "item_option_id": "WUHPNVNVCW2KBXZ36GT2BNZH",
                  "item_option_value_id": "O55AQ6U4HFWDAIPHFHURPMEA"
                },
                {
                  "item_option_id": "GYWZZUMPQGBNMBANC32WWSWC",
                  "item_option_value_id": "O7XQMPXSMFSGUSATAGARGX3E"
                }
              ]
            }
          },
          {
            "type": "ITEM_VARIATION",
            "id": "SOQTNT7336QXGHI3YK7ZZQ6O",
            "updated_at": "2020-10-17T04:44:20.494Z",
            "version": 1602909860494,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_variation_data": {
              "item_id": "EQVBSUZZ65RO2WWPFU6PLYWU",
              "name": "Small, Blue",
              "ordinal": 1,
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 2500,
                "currency": "USD"
              },
              "item_option_values": [
                {
                  "item_option_id": "WUHPNVNVCW2KBXZ36GT2BNZH",
                  "item_option_value_id": "O55AQ6U4HFWDAIPHFHURPMEA"
                },
                {
                  "item_option_id": "GYWZZUMPQGBNMBANC32WWSWC",
                  "item_option_value_id": "W55IT3LUEQI62LTLXOPLXYEL"
                }
              ]
            }
          },
          {
            "type": "ITEM_VARIATION",
            "id": "KI66FNZXAEGEPE42J2PPX6AJ",
            "updated_at": "2020-10-17T04:44:20.494Z",
            "version": 1602909860494,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_variation_data": {
              "item_id": "EQVBSUZZ65RO2WWPFU6PLYWU",
              "name": "Medium, RED",
              "ordinal": 2,
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 3000,
                "currency": "USD"
              },
              "item_option_values": [
                {
                  "item_option_id": "WUHPNVNVCW2KBXZ36GT2BNZH",
                  "item_option_value_id": "RJI7UGDMDVOHBEQJSASTWOOJ"
                },
                {
                  "item_option_id": "GYWZZUMPQGBNMBANC32WWSWC",
                  "item_option_value_id": "O7XQMPXSMFSGUSATAGARGX3E"
                }
              ]
            }
          },
          {
            "type": "ITEM_VARIATION",
            "id": "RHSUAWEXGNTQNQA55KNEYXOO",
            "updated_at": "2020-10-17T04:44:20.494Z",
            "version": 1602909860494,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_variation_data": {
              "item_id": "EQVBSUZZ65RO2WWPFU6PLYWU",
              "name": "Medium, Blue",
              "ordinal": 3,
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 3000,
                "currency": "USD"
              },
              "item_option_values": [
                {
                  "item_option_id": "WUHPNVNVCW2KBXZ36GT2BNZH",
                  "item_option_value_id": "RJI7UGDMDVOHBEQJSASTWOOJ"
                },
                {
                  "item_option_id": "GYWZZUMPQGBNMBANC32WWSWC",
                  "item_option_value_id": "W55IT3LUEQI62LTLXOPLXYEL"
                }
              ]
            }
          },
          {
            "type": "ITEM_VARIATION",
            "id": "AY6GSOG4ZZTYJ6RJPU2F4O6I",
            "updated_at": "2020-10-17T04:44:20.494Z",
            "version": 1602909860494,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_variation_data": {
              "item_id": "EQVBSUZZ65RO2WWPFU6PLYWU",
              "name": "Large, RED",
              "ordinal": 4,
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 3500,
                "currency": "USD"
              },
              "item_option_values": [
                {
                  "item_option_id": "WUHPNVNVCW2KBXZ36GT2BNZH",
                  "item_option_value_id": "56QF4FR2BC2D67K4QJ2U2KYC"
                },
                {
                  "item_option_id": "GYWZZUMPQGBNMBANC32WWSWC",
                  "item_option_value_id": "O7XQMPXSMFSGUSATAGARGX3E"
                }
              ]
            }
          },
          {
            "type": "ITEM_VARIATION",
            "id": "GBUW47ZH7I7PZI6E5XCWPLGD",
            "updated_at": "2020-10-17T04:44:20.494Z",
            "version": 1602909860494,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_variation_data": {
              "item_id": "EQVBSUZZ65RO2WWPFU6PLYWU",
              "name": "Large, Blue",
              "ordinal": 5,
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 3500,
                "currency": "USD"
              },
              "item_option_values": [
                {
                  "item_option_id": "WUHPNVNVCW2KBXZ36GT2BNZH",
                  "item_option_value_id": "56QF4FR2BC2D67K4QJ2U2KYC"
                },
                {
                  "item_option_id": "GYWZZUMPQGBNMBANC32WWSWC",
                  "item_option_value_id": "W55IT3LUEQI62LTLXOPLXYEL"
                }
              ]
            }
          }
        ],
        "product_type": "REGULAR",
        "item_options": [
          {
            "item_option_id": "WUHPNVNVCW2KBXZ36GT2BNZH"
          },
          {
            "item_option_id": "GYWZZUMPQGBNMBANC32WWSWC"
          }
        ]
      }
    }
  ],
  "id_mappings": [
    {
      "client_object_id": "#item_option_color",
      "object_id": "GYWZZUMPQGBNMBANC32WWSWC"
    },
    {
      "client_object_id": "#item_option_size",
      "object_id": "WUHPNVNVCW2KBXZ36GT2BNZH"
    },
    {
      "client_object_id": "#item",
      "object_id": "EQVBSUZZ65RO2WWPFU6PLYWU"
    },
    {
      "client_object_id": "#item_option_value_color_red",
      "object_id": "O7XQMPXSMFSGUSATAGARGX3E"
    },
    {
      "client_object_id": "#item_option_value_color_blue",
      "object_id": "W55IT3LUEQI62LTLXOPLXYEL"
    },
    {
      "client_object_id": "#item_option_value_size_small",
      "object_id": "O55AQ6U4HFWDAIPHFHURPMEA"
    },
    {
      "client_object_id": "#item_option_value_size_medium",
      "object_id": "RJI7UGDMDVOHBEQJSASTWOOJ"
    },
    {
      "client_object_id": "#item_option_value_size_large",
      "object_id": "56QF4FR2BC2D67K4QJ2U2KYC"
    },
    {
      "client_object_id": "#item_variation_small_red",
      "object_id": "6PRFCYBKD7QNDERVZP5FBDL7"
    },
    {
      "client_object_id": "#item_variation_medium_red",
      "object_id": "KI66FNZXAEGEPE42J2PPX6AJ"
    },
    {
      "client_object_id": "#item_variation_large_red",
      "object_id": "AY6GSOG4ZZTYJ6RJPU2F4O6I"
    },
    {
      "client_object_id": "#item_variation_small_blue",
      "object_id": "SOQTNT7336QXGHI3YK7ZZQ6O"
    },
    {
      "client_object_id": "#item_variation_medium_blue",
      "object_id": "RHSUAWEXGNTQNQA55KNEYXOO"
    },
    {
      "client_object_id": "#item_variation_large_blue",
      "object_id": "GBUW47ZH7I7PZI6E5XCWPLGD"
    }
  ]
}

Notice that the name and ordinal attributes of an item variation are no longer set in the request. They are set on the item options. Do not set the name and ordinal attributes on the item variation when using an item option value. The ordinal number shown in the response is computed as the matrix element position. For an N x M matrix, the matrix element, m_(i,j) has the ordinal number of M*i+j, where i=0, ..., N-1 and j=0, ..., M-1.

Link to section
Manage item variations with or without item options

When an item option is used as part of an item variation, the display order for an item variation is determined by the order of the associated item option values. The display name for an item variation is derived by combining the names of the item option values associated with the item variation. You must manage the name and ordinal number of an item variation through the item option.

You can continue to manage the name and ordinal value on the item variations when not using item options. Other attributes, such as inventory counts and SKU, are still maintained at the item variation level regardless of whether item options are used.

Link to section
Search for item variations using item options

The following cURL example searches for the small and red item variation with item options defining the size and color. Notice that the item option values (Small and RED) are referred to by the respective item option value IDs (item_option_value_ids).

Link to section
Request: Search for item variation by the item option values

Search Catalog Objects

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

curl https://connect.squareupsandbox.com/v2/catalog/search \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "object_types": [
      "ITEM"
    ],
    "query": {
      "item_variations_for_item_option_values_query": {
        "item_option_value_ids": [
          "O7XQMPXSMFSGUSATAGARGX3E",
          "O55AQ6U4HFWDAIPHFHURPMEA"
        ]
      }
    }
  }'

Link to section
Response

The request returns a successful response similar to the following. Because the request used the item_variations_for_item_option_values_query filter, only the matched item variations are returned.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

{
  "objects": [
    {
      "type": "ITEM_VARIATION",
      "id": "6PRFCYBKD7QNDERVZP5FBDL7",
      "updated_at": "2020-10-17T04:44:20.494Z",
      "version": 1602909860494,
      "is_deleted": false,
      "present_at_all_locations": true,
      "item_variation_data": {
        "item_id": "EQVBSUZZ65RO2WWPFU6PLYWU",
        "name": "Small, RED",
        "ordinal": 0,
        "pricing_type": "FIXED_PRICING",
        "price_money": {
          "amount": 2500,
          "currency": "USD"
        },
        "item_option_values": [
          {
            "item_option_id": "WUHPNVNVCW2KBXZ36GT2BNZH",
            "item_option_value_id": "O55AQ6U4HFWDAIPHFHURPMEA"
          },
          {
            "item_option_id": "GYWZZUMPQGBNMBANC32WWSWC",
            "item_option_value_id": "O7XQMPXSMFSGUSATAGARGX3E"
          }
        ]
      }
    }
  ],
  "latest_time": "2020-10-17T04:44:20.494Z"
}

Link to section
Request: Search for item variations by the RED item option value

To specify the RED option value in the search query, set the RED item option value ID (O7XQMPXSMFSGUSATAGARGX3E) on the item_variation_for_item_option_values_query filter.

Search Catalog Objects

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

curl https://connect.squareupsandbox.com/v2/catalog/search \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "object_types": [
      "ITEM"
    ],
    "query": {
      "item_variations_for_item_option_values_query": {
        "item_option_value_ids": [
          "O7XQMPXSMFSGUSATAGARGX3E"
        ]
      }
    }
  }'

Link to section
Response

The successful response includes three item variations including the RED item option, namely, the "Small, RED," "Medium, RED," and "Large, RED" item variations.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89

{
  "objects": [
    {
      "type": "ITEM_VARIATION",
      "id": "6PRFCYBKD7QNDERVZP5FBDL7",
      "updated_at": "2020-10-17T04:44:20.494Z",
      "version": 1602909860494,
      "is_deleted": false,
      "present_at_all_locations": true,
      "item_variation_data": {
        "item_id": "EQVBSUZZ65RO2WWPFU6PLYWU",
        "name": "Small, RED",
        "ordinal": 0,
        "pricing_type": "FIXED_PRICING",
        "price_money": {
          "amount": 2500,
          "currency": "USD"
        },
        "item_option_values": [
          {
            "item_option_id": "WUHPNVNVCW2KBXZ36GT2BNZH",
            "item_option_value_id": "O55AQ6U4HFWDAIPHFHURPMEA"
          },
          {
            "item_option_id": "GYWZZUMPQGBNMBANC32WWSWC",
            "item_option_value_id": "O7XQMPXSMFSGUSATAGARGX3E"
          }
        ]
      }
    },
    {
      "type": "ITEM_VARIATION",
      "id": "KI66FNZXAEGEPE42J2PPX6AJ",
      "updated_at": "2020-10-17T04:44:20.494Z",
      "version": 1602909860494,
      "is_deleted": false,
      "present_at_all_locations": true,
      "item_variation_data": {
        "item_id": "EQVBSUZZ65RO2WWPFU6PLYWU",
        "name": "Medium, RED",
        "ordinal": 2,
        "pricing_type": "FIXED_PRICING",
        "price_money": {
          "amount": 3000,
          "currency": "USD"
        },
        "item_option_values": [
          {
            "item_option_id": "WUHPNVNVCW2KBXZ36GT2BNZH",
            "item_option_value_id": "RJI7UGDMDVOHBEQJSASTWOOJ"
          },
          {
            "item_option_id": "GYWZZUMPQGBNMBANC32WWSWC",
            "item_option_value_id": "O7XQMPXSMFSGUSATAGARGX3E"
          }
        ]
      }
    },
    {
      "type": "ITEM_VARIATION",
      "id": "AY6GSOG4ZZTYJ6RJPU2F4O6I",
      "updated_at": "2020-10-17T04:44:20.494Z",
      "version": 1602909860494,
      "is_deleted": false,
      "present_at_all_locations": true,
      "item_variation_data": {
        "item_id": "EQVBSUZZ65RO2WWPFU6PLYWU",
        "name": "Large, RED",
        "ordinal": 4,
        "pricing_type": "FIXED_PRICING",
        "price_money": {
          "amount": 3500,
          "currency": "USD"
        },
        "item_option_values": [
          {
            "item_option_id": "WUHPNVNVCW2KBXZ36GT2BNZH",
            "item_option_value_id": "56QF4FR2BC2D67K4QJ2U2KYC"
          },
          {
            "item_option_id": "GYWZZUMPQGBNMBANC32WWSWC",
            "item_option_value_id": "O7XQMPXSMFSGUSATAGARGX3E"
          }
        ]
      }
    }
  ],
  "latest_time": "2020-10-17T04:44:20.494Z"
}

Link to section
Search for item variations by searchable attribute

The Catalog API supports various query filters to search for catalog objects. The name attribute is one of the searchable attributes.

The following cURL example illustrates how to search for item variations with "small red shirt" or "small red" set on their names:

Link to section
Request

Search Catalog Objects

1
2
3
4
5
6
7
8
9
10
11
12
13
14

curl https://connect.squareupsandbox.com/v2/catalog/search \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "text_query": {
        "keywords": [
          "Small red shirt"
        ]
      }
    }
  }'

Instead of using the "Small red shirt" phrase as a single element of the keywords list, you can specify a three-element list in the text_query expression as shown. The result is the same.

Search Catalog Objects

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

curl https://connect.squareupsandbox.com/v2/catalog/search \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "text_query": {
        "keywords": [
          "Small",
          "red",
          "shirt"
        ]
      }
    }
  }'

Link to section
Response

In the example catalog, there is only one item variation with the name of "Small red shirt". The successful response returns this object for the match.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

{
  "objects": [
    {
      "type": "ITEM_VARIATION",
      "id": "F3P54C436KUEUGMRCUFYBEIZ",
      "updated_at": "2020-10-17T00:08:15.13Z",
      "version": 1602893295130,
      "is_deleted": false,
      "present_at_all_locations": true,
      "item_variation_data": {
        "item_id": "3RJ4KVW64QXHXYDJ5CS6J4LE",
        "name": "Small red shirt",
        "ordinal": 0,
        "pricing_type": "FIXED_PRICING",
        "price_money": {
          "amount": 2500,
          "currency": "USD"
        }
      }
    }
  ],
  "latest_time": "2020-10-17T04:44:20.494Z"
}

Link to section
Request

Search Catalog Objects

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

curl https://connect.squareupsandbox.com/v2/catalog/search \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "text_query": {
        "keywords": [
          "Small",
          "red"
        ]
      }
    }
  }'

The order of the query expression list does not matter and punctuations are ignored.

Link to section
Response

In the example catalog, there is an item variation (named Small red shirt) without item options and another item variation (named Small, RED) with item option values defining the size and color. As the result, the previous request returns both for the match.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

{
  "objects": [
    {
      "type": "ITEM_VARIATION",
      "id": "F3P54C436KUEUGMRCUFYBEIZ",
      "updated_at": "2020-10-17T00:08:15.13Z",
      "version": 1602893295130,
      "is_deleted": false,
      "present_at_all_locations": true,
      "item_variation_data": {
        "item_id": "3RJ4KVW64QXHXYDJ5CS6J4LE",
        "name": "Small red shirt",
        "ordinal": 0,
        "pricing_type": "FIXED_PRICING",
        "price_money": {
          "amount": 2500,
          "currency": "USD"
        }
      }
    },
    {
      "type": "ITEM_VARIATION",
      "id": "6PRFCYBKD7QNDERVZP5FBDL7",
      "updated_at": "2020-10-17T04:44:20.494Z",
      "version": 1602909860494,
      "is_deleted": false,
      "present_at_all_locations": true,
      "item_variation_data": {
        "item_id": "EQVBSUZZ65RO2WWPFU6PLYWU",
        "name": "Small, RED",
        "ordinal": 0,
        "pricing_type": "FIXED_PRICING",
        "price_money": {
          "amount": 2500,
          "currency": "USD"
        },
        "item_option_values": [
          {
            "item_option_id": "WUHPNVNVCW2KBXZ36GT2BNZH",
            "item_option_value_id": "O55AQ6U4HFWDAIPHFHURPMEA"
          },
          {
            "item_option_id": "GYWZZUMPQGBNMBANC32WWSWC",
            "item_option_value_id": "O7XQMPXSMFSGUSATAGARGX3E"
          }
        ]
      }
    }
  ],
  "latest_time": "2020-10-17T04:44:20.494Z"
}

Link to section
Migrate item variations to use item options

You have three options to manage your catalog items.

Link to section
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 field, 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 need to manage the name and ordinal fields at the item variation level.

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

If you want 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. Be aware however that items using item options cannot be managed the same way as items that use the old item variation model. Your code needs 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.

Link to section
Option 3: Restructure your entire catalog to use item options

If you want to use item options for all your existing items, you 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 fields from the existing item variations.
Reference the item option values in the item variations.
Set the name and ordinal field for the item variation to be null or blank.
Send a BatchUpsertCatalogObjects request to update your catalog.

Link to section
Step 1: Retrieve the item and item variations you want to restructure

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

{
  "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"

      ... 

    }
  }
}

Link to section
Step 2: Create item options

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

Batch Upsert Catalog Objects

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76

curl https://connect.squareupsandbox.com/v2/catalog/batch-upsert \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "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"
                  }
                }
              ]
            }
          }
        ]
      }
    ]
  }'

Link to section
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 null:

Batch Upsert Catalog Objects

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126

curl https://connect.squareupsandbox.com/v2/catalog/batch-upsert \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "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"
                      }
                    ]
                  }
                }
              ]
            }
          }
        ]
      }
    ]
  }'

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.

Docs

Use Item Options to Manage Item Variations

On this page

Link to section
Item variations

Link to section
Create item variations related by size and color without item options

Link to section
Request

Link to section
Response

Link to section
Item options

Link to section
Create item variations related by size and color with item options

Link to section
Request

Link to section
Response

Link to section
Manage item variations with or without item options

Link to section
Search for item variations using item options

Link to section
Request: Search for item variation by the item option values

Link to section
Response

Link to section
Request: Search for item variations by the RED item option value

Link to section
Response

Link to section
Search for item variations by searchable attribute

Link to section
Request

Link to section
Response

Link to section
Request

Link to section
Response

Link to section
Migrate item variations to use item options

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

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

Link to section
Option 3: Restructure your entire catalog to use item options

Link to section
Step 1: Retrieve the item and item variations you want to restructure

Link to section
Step 2: Create item options

Link to section
Step 3: Associate item variation with item option values

On this page

Docs

Use Item Options to Manage Item Variations

On this page

Link to section Item variations

Link to section Create item variations related by size and color without item options

Link to section Request

Link to section Response

Link to section Item options

Link to section Create item variations related by size and color with item options

Link to section Request

Link to section Response

Link to section Manage item variations with or without item options

Link to section Search for item variations using item options

Link to section Request: Search for item variation by the item option values

Link to section Response

Link to section Request: Search for item variations by the RED item option value

Link to section Response

Link to section Search for item variations by searchable attribute

Link to section Request

Link to section Response

Link to section Request

Link to section Response

Link to section Migrate item variations to use item options

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

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

Link to section Option 3: Restructure your entire catalog to use item options

Link to section Step 1: Retrieve the item and item variations you want to restructure

Link to section Step 2: Create item options

Link to section Step 3: Associate item variation with item option values

On this page

Link to section
Item variations

Link to section
Create item variations related by size and color without item options

Link to section
Request

Link to section
Response

Link to section
Item options

Link to section
Create item variations related by size and color with item options

Link to section
Request

Link to section
Response

Link to section
Manage item variations with or without item options

Link to section
Search for item variations using item options

Link to section
Request: Search for item variation by the item option values

Link to section
Response

Link to section
Request: Search for item variations by the RED item option value

Link to section
Response

Link to section
Search for item variations by searchable attribute

Link to section
Request

Link to section
Response

Link to section
Request

Link to section
Response

Link to section
Migrate item variations to use item options

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

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

Link to section
Option 3: Restructure your entire catalog to use item options

Link to section
Step 1: Retrieve the item and item variations you want to restructure

Link to section
Step 2: Create item options

Link to section
Step 3: Associate item variation with item option values