Square API
Developer Home
Developer Docs
Square API

You are viewing an old version of the API
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.

Required permissions ITEMS_WRITE

Request Body
Name Description
idempotency_key
string
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.

Min Length 1
batches
Catalog​Object​Batch [ ]

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 updated_at field is ignored and replaced with a current timestamp, and its is_deleted field must not be set to true.

To modify an existing object, supply its ID. To create a new object, use an ID starting with #. These IDs may be used to create relationships between an object and attributes of other objects that reference it. For example, you can create a CatalogItem with ID #ABC and a CatalogItemVariation with its item_id attribute set to #ABC in order to associate the CatalogItemVariation with its parent CatalogItem.

Any #-prefixed IDs are valid only within a single atomic batch, and will be replaced by server-generated IDs.

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
Error [ ]

Information on any errors that encountered.
id_mappings
Catalog​Id​Mapping [ ]

The mapping between client and server IDs for this upsert.
objects
Catalog​Object [ ]

The created successfully created CatalogObjects.
updated_at
string

The database timestamp of this update in RFC 3339 format, e.g., "2016-09-04T23:59:33.123Z".

Examples

You are viewing an old version of the API
POST /v2/catalog/batch-upsert
cURL
  • cURL
  • Ruby
  • Python 
curl https://connect.squareup.com/v2/catalog/batch-upsert \
  -X POST \
  -H 'Square-Version: 2019-12-17' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -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
            }
          }
        ]
      }
    ]
  }'
Response JSON 
{
  "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"
    }
  ]
}

Share Feedback

Thanks for visiting the Square API documentation. What's on your mind?