Batch upsert catalog objects
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.
Name | Description |
---|---|
idempotency_
Required
|
A value you specify that uniquely identifies this request among all your requests. A common way to create a valid idempotency key is to use a Universally unique identifier (UUID). If you're unsure whether a particular request was successful, you can reattempt it with the same idempotency key without worrying about creating duplicate objects. See Idempotency for more information. |
batches
Required
|
A batch of CatalogObjects to be inserted/updated atomically. The objects within a batch will be inserted in an all-or-nothing fashion, i.e., if an error occurs attempting to insert or update an object within a batch, the entire batch will be rejected. However, an error in one batch will not affect other batches within the same request. For each object, its To modify an existing object, supply its ID. To create a new object, use an ID starting
with Any Each batch may contain up to 1,000 objects. The total number of objects across all batches for a single request may not exceed 10,000. If either of these limits is violated, an error will be returned and no objects will be inserted or updated. |
Response Fields
Name | Description |
---|---|
errors
|
Any errors that occurred during the request. |
objects
|
The created successfully created CatalogObjects. |
updated_
|
The database timestamp of this update in RFC 3339 format, e.g., "2016-09-04T23:59:33.123Z". Examples for January 25th, 2020 6:25:34pm Pacific Standard Time: UTC: 2020-01-26T02:25:34Z Pacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00 |
id_
|
The mapping between client and server IDs for this upsert. |
Examples
- cURL
- Ruby
- Python
- C#
- Java
- PHP
- Node.js
curl https://connect.squareup.com/v2/catalog/batch-upsert \
-X POST \
-H 'Square-Version: 2020-12-16' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"idempotency_key": "789ff020-f723-43a9-b4b5-43b5dc1fa3dc",
"batches": [
{
"objects": [
{
"type": "ITEM",
"id": "#Tea",
"present_at_all_locations": true,
"item_data": {
"name": "Tea",
"description": "Hot Leaf Juice",
"category_id": "#Beverages",
"tax_ids": [
"#SalesTax"
],
"variations": [
{
"type": "ITEM_VARIATION",
"id": "#Tea_Mug",
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "#Tea",
"name": "Mug",
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 150,
"currency": "USD"
}
}
}
]
}
},
{
"type": "ITEM",
"id": "#Coffee",
"present_at_all_locations": true,
"item_data": {
"name": "Coffee",
"description": "Hot Bean Juice",
"category_id": "#Beverages",
"tax_ids": [
"#SalesTax"
],
"variations": [
{
"type": "ITEM_VARIATION",
"id": "#Coffee_Regular",
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "#Coffee",
"name": "Regular",
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 250,
"currency": "USD"
}
}
},
{
"type": "ITEM_VARIATION",
"id": "#Coffee_Large",
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "#Coffee",
"name": "Large",
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 350,
"currency": "USD"
}
}
}
]
}
},
{
"type": "CATEGORY",
"id": "#Beverages",
"present_at_all_locations": true,
"category_data": {
"name": "Beverages"
}
},
{
"type": "TAX",
"id": "#SalesTax",
"present_at_all_locations": true,
"tax_data": {
"name": "Sales Tax",
"calculation_phase": "TAX_SUBTOTAL_PHASE",
"inclusion_type": "ADDITIVE",
"percentage": "5.0",
"applies_to_custom_amounts": true,
"enabled": true
}
}
]
}
]
}'
{
"objects": [
{
"type": "ITEM",
"id": "ZSDZN34NAXDLC6D5ZQMNSOUM",
"updated_at": "2017-05-10T18:48:39.798Z",
"version": 1494442119798,
"is_deleted": false,
"present_at_all_locations": true,
"item_data": {
"name": "Tea",
"description": "Hot Leaf Juice",
"category_id": "LYT72K3WGJFFCIMB63XARP3I",
"tax_ids": [
"XHSHLHNWSI3HVI4BW5ZUZXI3"
],
"variations": [
{
"type": "ITEM_VARIATION",
"id": "NAYHET5R52MIYCEF34ZMAHFM",
"updated_at": "2017-05-10T18:48:39.798Z",
"version": 1494442119798,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "ZSDZN34NAXDLC6D5ZQMNSOUM",
"name": "Mug",
"ordinal": 0,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 150,
"currency": "USD"
}
}
}
]
}
},
{
"type": "ITEM",
"id": "PJMCEBHHUS3OKDB6PYUHLCPP",
"updated_at": "2017-05-10T18:48:39.798Z",
"version": 1494442119798,
"is_deleted": false,
"present_at_all_locations": true,
"item_data": {
"name": "Coffee",
"description": "Hot Bean Juice",
"category_id": "LYT72K3WGJFFCIMB63XARP3I",
"tax_ids": [
"XHSHLHNWSI3HVI4BW5ZUZXI3"
],
"variations": [
{
"type": "ITEM_VARIATION",
"id": "OTYDX45SPG7LJQUVCBZI4INH",
"updated_at": "2017-05-10T18:48:39.798Z",
"version": 1494442119798,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "PJMCEBHHUS3OKDB6PYUHLCPP",
"name": "Regular",
"ordinal": 0,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 250,
"currency": "USD"
}
}
},
{
"type": "ITEM_VARIATION",
"id": "GZDA3JB37FYVOPI4AOEBOITI",
"updated_at": "2017-05-10T18:48:39.798Z",
"version": 1494442119798,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "PJMCEBHHUS3OKDB6PYUHLCPP",
"name": "Large",
"ordinal": 1,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 350,
"currency": "USD"
}
}
}
]
}
},
{
"type": "CATEGORY",
"id": "LYT72K3WGJFFCIMB63XARP3I",
"updated_at": "2017-05-10T18:48:39.798Z",
"version": 1494442119798,
"is_deleted": false,
"present_at_all_locations": true,
"category_data": {
"name": "Beverages"
}
},
{
"type": "TAX",
"id": "XHSHLHNWSI3HVI4BW5ZUZXI3",
"updated_at": "2017-05-10T18:48:39.798Z",
"version": 1494442119798,
"is_deleted": false,
"present_at_all_locations": true,
"tax_data": {
"name": "Sales Tax",
"calculation_phase": "TAX_SUBTOTAL_PHASE",
"inclusion_type": "ADDITIVE",
"percentage": "5.0",
"applies_to_custom_amounts": true,
"enabled": true
}
}
],
"id_mappings": [
{
"client_object_id": "#Tea",
"object_id": "ZSDZN34NAXDLC6D5ZQMNSOUM"
},
{
"client_object_id": "#Coffee",
"object_id": "PJMCEBHHUS3OKDB6PYUHLCPP"
},
{
"client_object_id": "#Beverages",
"object_id": "LYT72K3WGJFFCIMB63XARP3I"
},
{
"client_object_id": "#SalesTax",
"object_id": "XHSHLHNWSI3HVI4BW5ZUZXI3"
},
{
"client_object_id": "#Tea_Mug",
"object_id": "NAYHET5R52MIYCEF34ZMAHFM"
},
{
"client_object_id": "#Coffee_Regular",
"object_id": "OTYDX45SPG7LJQUVCBZI4INH"
},
{
"client_object_id": "#Coffee_Large",
"object_id": "GZDA3JB37FYVOPI4AOEBOITI"
}
]
}