Catalog
BatchUpsertCatalogObjects
Creates or updates up to 10,000 target objects based on the provided list of objects. The target objects are grouped into batches and each batch is inserted/updated in an all-or-nothing manner. If an object within a batch is malformed in some way, or violates a database constraint, the entire batch containing that item will be disregarded. However, other batches in the same request may still succeed. Each batch may contain up to 1,000 objects, and batches will be processed in order as long as the total object count for the request (items, variations, modifier lists, discounts, and taxes) is no more than 10,000.
To ensure consistency, only one update request is processed at a time per seller account. While one (batch or non-batch) update request is being processed, other (batched and non-batched) update requests are rejected with the 429 error code.
post/v2/catalog/batch-upsert
Request body
Example request
{
"batches": [
{
"objects": [
{
"id": "#Tea",
"item_data": {
"categories": [
{
"id": "#Beverages"
}
],
"description_html": "<p><strong>Hot</strong> Leaf Juice</p>",
"name": "Tea",
"tax_ids": [
"#SalesTax"
],
"variations": [
{
"id": "#Tea_Mug",
"item_variation_data": {
"item_id": "#Tea",
"name": "Mug",
"price_money": {
"amount": 150,
"currency": "USD"
},
"pricing_type": "FIXED_PRICING"
},
"present_at_all_locations": true,
"type": "ITEM_VARIATION"
}
]
},
"present_at_all_locations": true,
"type": "ITEM"
},
{
"id": "#Coffee",
"item_data": {
"categories": [
{
"id": "#Beverages"
}
],
"description_html": "<p>Hot <em>Bean Juice</em></p>",
"name": "Coffee",
"tax_ids": [
"#SalesTax"
],
"variations": [
{
"id": "#Coffee_Regular",
"item_variation_data": {
"item_id": "#Coffee",
"name": "Regular",
"price_money": {
"amount": 250,
"currency": "USD"
},
"pricing_type": "FIXED_PRICING"
},
"present_at_all_locations": true,
"type": "ITEM_VARIATION"
},
{
"id": "#Coffee_Large",
"item_variation_data": {
"item_id": "#Coffee",
"name": "Large",
"price_money": {
"amount": 350,
"currency": "USD"
},
"pricing_type": "FIXED_PRICING"
},
"present_at_all_locations": true,
"type": "ITEM_VARIATION"
}
]
},
"present_at_all_locations": true,
"type": "ITEM"
},
{
"category_data": {
"name": "Beverages"
},
"id": "#Beverages",
"present_at_all_locations": true,
"type": "CATEGORY"
},
{
"id": "#SalesTax",
"present_at_all_locations": true,
"tax_data": {
"applies_to_custom_amounts": true,
"calculation_phase": "TAX_SUBTOTAL_PHASE",
"enabled": true,
"inclusion_type": "ADDITIVE",
"name": "Sales Tax",
"percentage": "5.0"
},
"type": "TAX"
}
]
}
],
"idempotency_key": "789ff020-f723-43a9-b4b5-43b5dc1fa3dc"
}Response
Success
Example response
{
"id_mappings": [
{
"client_object_id": "#Tea",
"object_id": "67GA7XA2FWMRYY2VCONTYZJR"
},
{
"client_object_id": "#Coffee",
"object_id": "MQ4TZKOG3SR2EQI3TWEK4AH7"
},
{
"client_object_id": "#Beverages",
"object_id": "XCS4SCGN4WQYE2VU4U3TKXEH"
},
{
"client_object_id": "#SalesTax",
"object_id": "HP5VNYPKZKTNCKZ2Z5NPUH6A"
},
{
"client_object_id": "#Tea_Mug",
"object_id": "CAJBHUIQH7ONTSZI2KTVOUP6"
},
{
"client_object_id": "#Coffee_Regular",
"object_id": "GY2GXJTVVPQAPW43GFRR3NG6"
},
{
"client_object_id": "#Coffee_Large",
"object_id": "JE6VHPSRQL6IWSN26C36CJ7W"
}
],
"objects": [
{
"created_at": "2023-11-30T19:24:35.4Z",
"id": "67GA7XA2FWMRYY2VCONTYZJR",
"is_deleted": false,
"item_data": {
"categories": [
{
"id": "XCS4SCGN4WQYE2VU4U3TKXEH",
"ordinal": -2251731094208512
}
],
"description": "Hot Leaf Juice",
"description_html": "<p><strong>Hot</strong> Leaf Juice</p>",
"description_plaintext": "Hot Leaf Juice",
"is_archived": false,
"is_taxable": true,
"name": "Tea",
"product_type": "REGULAR",
"tax_ids": [
"HP5VNYPKZKTNCKZ2Z5NPUH6A"
],
"variations": [
{
"created_at": "2023-11-30T19:24:35.4Z",
"id": "CAJBHUIQH7ONTSZI2KTVOUP6",
"is_deleted": false,
"item_variation_data": {
"item_id": "67GA7XA2FWMRYY2VCONTYZJR",
"name": "Mug",
"ordinal": 0,
"price_money": {
"amount": 150,
"currency": "USD"
},
"pricing_type": "FIXED_PRICING",
"sellable": true,
"stockable": true
},
"present_at_all_locations": true,
"type": "ITEM_VARIATION",
"updated_at": "2023-11-30T19:24:35.4Z",
"version": 1701372275400
}
]
},
"present_at_all_locations": true,
"type": "ITEM",
"updated_at": "2023-11-30T19:24:35.4Z",
"version": 1701372275400
},
{
"created_at": "2023-11-30T19:24:35.4Z",
"id": "MQ4TZKOG3SR2EQI3TWEK4AH7",
"is_deleted": false,
"item_data": {
"categories": [
{
"id": "XCS4SCGN4WQYE2VU4U3TKXEH",
"ordinal": -2251662374731776
}
],
"description": "Hot Bean Juice",
"description_html": "<p>Hot <em>Bean Juice</em></p>",
"description_plaintext": "Hot Bean Juice",
"is_archived": false,
"is_taxable": true,
"name": "Coffee",
"product_type": "REGULAR",
"tax_ids": [
"HP5VNYPKZKTNCKZ2Z5NPUH6A"
],
"variations": [
{
"created_at": "2023-11-30T19:24:35.4Z",
"id": "GY2GXJTVVPQAPW43GFRR3NG6",
"is_deleted": false,
"item_variation_data": {
"item_id": "MQ4TZKOG3SR2EQI3TWEK4AH7",
"name": "Regular",
"ordinal": 0,
"price_money": {
"amount": 250,
"currency": "USD"
},
"pricing_type": "FIXED_PRICING",
"sellable": true,
"stockable": true
},
"present_at_all_locations": true,
"type": "ITEM_VARIATION",
"updated_at": "2023-11-30T19:24:35.4Z",
"version": 1701372275400
},
{
"created_at": "2023-11-30T19:24:35.4Z",
"id": "JE6VHPSRQL6IWSN26C36CJ7W",
"is_deleted": false,
"item_variation_data": {
"item_id": "MQ4TZKOG3SR2EQI3TWEK4AH7",
"name": "Large",
"ordinal": 1,
"price_money": {
"amount": 350,
"currency": "USD"
},
"pricing_type": "FIXED_PRICING",
"sellable": true,
"stockable": true
},
"present_at_all_locations": true,
"type": "ITEM_VARIATION",
"updated_at": "2023-11-30T19:24:35.4Z",
"version": 1701372275400
}
]
},
"present_at_all_locations": true,
"type": "ITEM",
"updated_at": "2023-11-30T19:24:35.4Z",
"version": 1701372275400
},
{
"category_data": {
"category_type": "REGULAR_CATEGORY",
"is_top_level": true,
"name": "Beverages",
"online_visibility": true,
"parent_category": {
"ordinal": -2250837741010944
}
},
"created_at": "2023-11-30T19:24:35.4Z",
"id": "XCS4SCGN4WQYE2VU4U3TKXEH",
"is_deleted": false,
"present_at_all_locations": true,
"type": "CATEGORY",
"updated_at": "2023-11-30T19:24:35.4Z",
"version": 1701372275400
},
{
"created_at": "2023-11-30T19:24:35.4Z",
"id": "HP5VNYPKZKTNCKZ2Z5NPUH6A",
"is_deleted": false,
"present_at_all_locations": true,
"tax_data": {
"applies_to_custom_amounts": true,
"calculation_phase": "TAX_SUBTOTAL_PHASE",
"enabled": true,
"inclusion_type": "ADDITIVE",
"name": "Sales Tax",
"percentage": "5.0"
},
"type": "TAX",
"updated_at": "2023-11-30T19:24:35.4Z",
"version": 1701372275400
}
]
}