Upsert catalog object

POST

/v2/catalog/object

Creates a new or updates the specified CatalogObject.

To ensure consistency, only one update request is processed at a time per seller account. While one (batch or non-batch) update request is being processed, other (batched and non-batched) update requests are rejected with the 429 error code.

Permissions:ITEMS_WRITE

Guide

Build a Simple Catalog

Try in API Explorer

Link to section

Request body

Example code

Link to section

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

Max Length

128

Link to section

object

Required

A CatalogObject to be created or updated.

For updates, the object must be active (the is_deleted field is not true).
For creates, the object ID must start with #. The provided ID is replaced with a server-generated ID.

Link to section

Response fields

Link to section

errors

Any errors that occurred during the request.

Link to section

catalog_object

The successfully created or updated CatalogObject.

Link to section

id_mappings

The mapping between client and server IDs for this upsert.

Link to section

Examples

All versions ->

POST /v2/catalog/object

curl https://connect.squareup.com/v2/catalog/object \
  -X POST \
  -H 'Square-Version: 2025-05-21' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "af3d1afc-7212-4300-b463-0bfc5314a5ae",
    "object": {
      "id": "#Cocoa",
      "type": "ITEM",
      "item_data": {
        "abbreviation": "Ch",
        "description": "Hot Chocolate",
        "name": "Cocoa",
        "variations": [
          {
            "id": "#Small",
            "type": "ITEM_VARIATION",
            "item_variation_data": {
              "item_id": "#Cocoa",
              "name": "Small",
              "pricing_type": "VARIABLE_PRICING"
            }
          },
          {
            "id": "#Large",
            "type": "ITEM_VARIATION",
            "item_variation_data": {
              "item_id": "#Cocoa",
              "name": "Large",
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 400,
                "currency": "USD"
              }
            }
          }
        ]
      }
    }
  }'

Response JSON

{
  "catalog_object": {
    "type": "ITEM",
    "id": "R2TA2FOBUGCJZNIWJSOSNAI4",
    "updated_at": "2021-06-14T15:51:39.021Z",
    "version": 1623685899021,
    "is_deleted": false,
    "present_at_all_locations": true,
    "item_data": {
      "name": "Cocoa",
      "description": "Hot Chocolate",
      "abbreviation": "Ch",
      "variations": [
        {
          "type": "ITEM_VARIATION",
          "id": "QRT53UP4LITLWGOGBZCUWP63",
          "updated_at": "2021-06-14T15:51:39.021Z",
          "version": 1623685899021,
          "is_deleted": false,
          "present_at_all_locations": true,
          "item_variation_data": {
            "item_id": "R2TA2FOBUGCJZNIWJSOSNAI4",
            "name": "Small",
            "ordinal": 0,
            "pricing_type": "VARIABLE_PRICING",
            "stockable": true
          }
        },
        {
          "type": "ITEM_VARIATION",
          "id": "NS77DKEIQ3AEQTCP727DSA7U",
          "updated_at": "2021-06-14T15:51:39.021Z",
          "version": 1623685899021,
          "is_deleted": false,
          "present_at_all_locations": true,
          "item_variation_data": {
            "item_id": "R2TA2FOBUGCJZNIWJSOSNAI4",
            "name": "Large",
            "ordinal": 1,
            "pricing_type": "FIXED_PRICING",
            "price_money": {
              "amount": 400,
              "currency": "USD"
            },
            "stockable": true
          }
        }
      ],
      "product_type": "REGULAR"
    }
  },
  "id_mappings": [
    {
      "client_object_id": "#Cocoa",
      "object_id": "R2TA2FOBUGCJZNIWJSOSNAI4"
    },
    {
      "client_object_id": "#Small",
      "object_id": "QRT53UP4LITLWGOGBZCUWP63"
    },
    {
      "client_object_id": "#Large",
      "object_id": "NS77DKEIQ3AEQTCP727DSA7U"
    }
  ]
}

Upsert catalog object

Request body

Response fields

Error descriptions