batch-upsert-catalog-objects-request.md

Batch Upsert Catalog Objects Request

Structure

Batch Upsert Catalog Objects Request

Fields

Name	Type	Tags	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. Constraints: Minimum Length: 1
batches	List of Catalog Object Batch	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.

Example (as JSON)

{
  "batches": [
    {
      "objects": [
        {
          "id": "#Tea",
          "item_data": {
            "category_id": "#Beverages",
            "description": "Hot Leaf Juice",
            "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": {
            "category_id": "#Beverages",
            "description": "Hot Bean Juice",
            "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"
}