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

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

POST /v2/catalog/object

Creates or updates the target CatalogObject.

Permissions
ITEMS_WRITE
Guide
Build a Simple Catalog 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
object
CatalogObject
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
errors
Error [ ]

Any errors that occurred during the request.
catalog_object
CatalogObject

The successfully created or updated CatalogObject.
id_mappings
CatalogIdMapping [ ]

The mapping between client and server IDs for this upsert.

Examples

Example:
You are viewing an old version of the API
POST /v2/catalog/object
cURL
  • cURL
  • Ruby
  • Python
  • C#
  • Java
  • PHP
  • Node.js 
curl https://connect.squareup.com/v2/catalog/object \
  -X POST \
  -H 'Square-Version: 2022-09-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"
    }
  ]
}

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"
    }
  ]
}