• Example searches: “transaction”, “CreateOrder”, “/v2/locations”, “inventory”, “delete customer”

You are viewing an old version of the API
Batch upsert catalog objects

POST /v2/catalog/batch-upsert

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.

Permissions
ITEMS_WRITE
 Try in API Explorer

Request Body

Example code
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
CatalogObjectBatch [ ]
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 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 [ ]

Any errors that occurred during the request.
objects
CatalogObject [ ]

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 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_mappings
CatalogIdMapping [ ]

The mapping between client and server IDs for this upsert.

Examples

You are viewing an old version of the API
POST /v2/catalog/batch-upsert
cURL
  • cURL
  • Ruby
  • Python
  • C#
  • Java
  • PHP
  • Node.js 
curl https://connect.squareup.com/v2/catalog/batch-upsert \
  -X POST \
  -H 'Square-Version: 2022-09-21' \
  -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
            }
          }
        ]
      }
    ]
  }'
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",
        "description_html": "<p><strong>Hot</strong> Leaf Juice</p>",
        "description_plaintext": "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",
        "description_html": "<p>Hot <em>Bean Juice</em></p>",
        "description_plaintext": "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"
    }
  ]
}

Error Descriptions
400 Bad request GENERIC_DECLINE

Square received a decline without any additional information. If the payment information seems correct, the buyer can contact their issuer to ask for more information.

 >
400 Bad request 
{
  "errors": [
    {
      "code": "GENERIC_DECLINE",
      "category": "PAYMENT_METHOD_ERROR"
    }
  ]
}