BatchUpsertCatalogObjects returns "nonexistent object" for an ITEM that RetrieveCatalogObject confirms exists (Production)

Questions
1

Environment: Production
API version: 2025-01-23
Endpoint: POST /v2/catalog/batch-upsert

Issue

Calling BatchUpsertCatalogObjects to update an existing ITEM returns:

Invalid Object with Id: 2BMASGZCZUZIAT3DEZWXURNY [object_id=2BMASGZCZUZIAT3DEZWXURNY]
Received request to update nonexistent object 2BMASGZCZUZIAT3DEZWXURNY.

However, calling RetrieveCatalogObject for the same ID, on the same account/environment, immediately before the failed write, succeeds and returns a fully valid, non-deleted ITEM (is_deleted: false, present_at_all_locations: true), including its ITEM_VARIATION child.

What I’ve already ruled out

  • Not a sandbox/production mismatch — confirmed both calls hit Production.
  • Not a stale/reused idempotency key — regenerated and retried with a fresh UUID.
  • Object is not deleted and is present at all locations per the GET response.

RetrieveCatalogObject response (relevant excerpt)

{
  "object": {
    "type": "ITEM",
    "id": "2BMASGZCZUZIAT3DEZWXURNY",
    "version": 1789713787448,
    "is_deleted": false,
    "present_at_all_locations": true,
    "item_data": {
      "name": "Mrs Balls Chutney Original 470g",
      "variations": [
        {
          "id": "4MCMKIRRDTU2QJLLFD5HNUS4",
          "item_variation_data": {
            "item_id": "2BMASGZCZUZIAT3DEZWXURNY",
            "sku": "SM-MRB-ORI-470G",
            "item_variation_vendor_info_ids": ["7EXT33FC5NGJGFIOV7GW5CC2"]
          }
        }
      ]
    }
  }
}

BatchUpsertCatalogObjects request that fails (full body)

{
  "idempotency_key": "3a5bab22-5f1a-4591-b35b-7a737cc71dea",
  "batches": [
    {
      "objects": [
        {
          "type": "ITEM",
          "id": "2BMASGZCZUZIAT3DEZWXURNY",
          "item_data": {
            "name": "Mrs Balls Chutney Original 470g",
            "description": "The truth of the matter? A flavour this unforgettable will forever inspire any food lover's chatter… no matter the meal, there's no denying it's incomplete 'til you've added this original South African chutney sauce in the mix!",
            "variations": [
              {
                "type": "ITEM_VARIATION",
                "id": "4MCMKIRRDTU2QJLLFD5HNUS4",
                "item_variation_data": {
                  "name": "Regular",
                  "sku": "SM-MRB-ORI-470G",
                  "upc": "6001092500052",
                  "pricing_type": "FIXED_PRICING",
                  "price_money": {
                    "amount": 469,
                    "currency": "GBP"
                  },
                  "track_inventory": true
                }
              }
            ],
            "description_html": "<meta charset=\"UTF-8\"><span>The truth of the matter? A flavour this unforgettable will forever inspire any food lover's chatter… no matter the meal, there's no denying it's incomplete 'til you've added this original South African chutney sauce in the mix!</span>"
          }
        }
      ]
    }
  ]
}

Any guidance on what internally causes “nonexistent object” for an object confirmed to exist via GET would be appreciated.

3

@Ranjan could you please provide your Application ID?

6

@Ranjan - In your request, you’re missing the required version field. See documentation here: Update Catalog Objects .

The error that Square returns may seem a bit misleading, but the system is unable to identify an item without a combination of the id, type, and version.