You are viewing an old version of the API
Upsert catalog object

Creates or updates the target CatalogObject

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
object
Catalog​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.

Response Fields

Name Description
catalog_object
Catalog​Object

The successfully created or updated CatalogObject.

errors
Error [ ]

Information on any errors encountered.

id_mappings
Catalog​Id​Mapping [ ]

The mapping between client and server IDs for this upsert.

Examples

You are viewing an old version of the API
POST /v2/catalog/object
cURL
  • cURL
  • Ruby
  • Python
curl https://connect.squareup.com/v2/catalog/object \
  -X POST \
  -H 'Square-Version: 2019-11-20' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -d '{
    "idempotency_key": "af3d1afc-7212-4300-b463-0bfc5314a5ae",
    "object": {
      "type": "ITEM",
      "id": "#Cocoa",
      "item_data": {
        "name": "Cocoa",
        "description": "Hot chocolate",
        "abbreviation": "Ch"
      }
    }
  }'
Response JSON
{
  "catalog_object": {
    "type": "ITEM",
    "id": "7SB3ZQYJ5GDMVFL7JK46JCHT",
    "updated_at": "2016-11-16T22:32:42.996Z",
    "version": 1479335562996,
    "is_deleted": false,
    "item_data": {
      "name": "Cocoa",
      "description": "Hot chocolate",
      "abbreviation": "Ch"
    }
  },
  "id_mappings": [
    {
      "client_object_id": "#Cocoa",
      "object_id": "7SB3ZQYJ5GDMVFL7JK46JCHT"
    }
  ]
}

Share Feedback

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