Learn how to manage uploaded images using the Square Catalog API.
Docs Home
Dev Essentials
Payments Commerce Customers Staff Merchants
Partnerships
Release notes

Docs

Docs Home
Dev Essentials
Payments
Commerce
Customers
Staff
Merchants
Partnerships
Release notes
Docs
Catalog API

Manage Images in a Square Catalog Beta release
This is pre-release documentation for an API in public beta and is subject to change.

After uploading images and possibly attaching them to objects, you can perform the following image-management tasks:

  • Call UpdateCatalogImage to replace the image file of an existing CatalogImage object.

  • Call UpserCatalogObject to attach an uploaded image to an image-supporting object.

  • Call UpsertCatalogObject to rearrange the order of the attached images by reshuffling the elements of the image_ids list of the target object.

  • Call UpsertCatalogObject to detach an image from an image-supporting object by removing the image object ID from the object's image_ids list.

  • Call DeleteCatalogObject to remove the image object from the catalog and detach the image object from its attached object.

In the following sections, you learn how to use the Catalog API to perform these tasks in detail.

Link to section
Replace the image file of a CatalogImage object

To replace the image file of a CatalogImage object with a new image file, call the new UpdateCatalogImage endpoint, supplying the new image file in the input. The result retains the ID and other attributes of the CatalogItem object, but swaps the existing image file with the new one. Any attachment of this image object to an image-supporting catalog object remains intact.

Note

Updating the image file has no effect on other attributes of the CatalogImage object. To modify other mutable attributes of the CatalogImage object, call the UpsertCatalogObject endpoint.

Link to section
Request

The following example shows how to call the UpdateCatalogImage endpoint to replace the existing image file (image_example.png) in the previously created CatalogImage object (BQC5NCY7VIKL6WQN5MOBJL3V) with a new image file (image_example_new.png):

Update Catalog Image
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
curl https://connect.squareupsandbox.com/v2/catalog/images/BQC5NCY7VIKL6WQN5MOBJL3V \
  -X PUT \
  -H 'Square-Version: 2023-08-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Accept: application/json' \
  -F 'file=@image_example_new.png' \
  -F 'request={
    "idempotency_key": "{UNIQUE_KEY}"
  }'
Try in API Explorer

Link to section
Response

The successful response returns the CatalogImage object as follows:

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
{
    "image": {
        "type": "IMAGE",
        "id": "BQC5NCY7VIKL6WQN5MOBJL3V",
        "updated_at": "2021-12-15T20:03:45.142Z",
        "created_at": "2021-12-15T05:36:15.441Z",
        "version": 1632168225142,
        "is_deleted": false,
        "present_at_all_locations": true,
        "image_data": {
            "name": "Image name",
            "url": "https://items-images-staging.s3.us-west-2.amazonaws.com/files/{UNIQUE_IMAGE_ID}/original.png",
            "caption": "Image caption"
        }
    }
}

The resulting image object has an updated version and updated timestamp. If the image file in the request is different from the existing image file, the UNQIQUE_IMAGE_ID assumes a new value. If the image file in the request is the same as the existing one, the UQNIUE_IMAGE_ID value remains the same.

Link to section
Attach an uploaded image to an object

Suppose you've uploaded an image file to the catalog. The image file is encapsulated by a CatalogImage object. To use the Catalog API to attach the uploaded image to a catalog item, item variation, category or modifier list, call UpsertCatalogObject or BatchUpsertCatalogObjects, specifying a new or existing object and the ID of the catalog image object in the image_ids list of the object.

UpsertCatalogObject can be used to create a new catalog object (other than CatalogImage) or to update attributes of a catalog object (including CatalogImage).

Link to section
Attach an uploaded image to a new item

To create a new item and attach an uploaded image (the ID of which is XOMHAUUSKU2XWHRQMXU22LXP) to it at the same time, call UpsertCatalogObject as follows:

Link to section
Request

Upsert Catalog Object
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
curl https://connect.squareupsandbox.com/v2/catalog/object \
  -X POST \
  -H 'Square-Version: 2023-08-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "object": {
      "id": "#item",
      "type": "ITEM",
      "item_data": {
        "image_ids": [
          "XOMHAUUSKU2XWHRQMXU22LXP"
        ],
        "description": "test item to attach images to",
        "name": "Item with images",
        "product_type": "REGULAR",
        "variations": [
          {
            "id": "#variation",
            "type": "ITEM_VARIATION",
            "item_variation_data": {
              "name": "Item for sale",
              "price_money": {
                "amount": 1999,
                "currency": "USD"
              },
              "pricing_type": "FIXED_PRICING"
            }
          }
        ]
      }
    }
  }'
Try in API Explorer

The specified CatalogItem is a new instance because a temporary ID (#item) is used.

Did you know?

To attach an image to an object using a version prior to 2021-12-15, set the image object ID on the legacy image_id attribute, instead of in the image_ids list.

Link to section
Response

The successful response returns the newly created item (of the Square-generated ID of BDWYGZO5QQWWEVFV6PAEP3BS) with the image_ids list containing the specified image object ID (7WWYBOW5AYLEWFW62HQX7EP4).

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
  • 38
  • 39
  • 40
  • 41
  • 42
  • 43
  • 44
  • 45
  • 46
  • 47
  • 48
  • 49
  • 50
  • 51
  • 52
{
    "catalog_object": {
        "type": "ITEM",
        "id": "JOIBESOPRL42QUMKXR57SEQA",
        "updated_at": "2021-12-15T04:14:22.829Z",
        "created_at": "2021-12-15T04:14:22.829Z",
        "version": 1638936862829,
        "is_deleted": false,
        "present_at_all_locations": true,
        "item_data": {
            "name": "Item with images",
            "description": "test item to attach images to",
            "variations": [
                {
                    "type": "ITEM_VARIATION",
                    "id": "7X7ZFRSJAPOIJOYQ2MVGZFXL",
                    "updated_at": "2021-12-15T04:14:22.829Z",
                    "created_at": "2021-12-15T04:14:22.829Z",
                    "version": 1638936862829,
                    "is_deleted": false,
                    "present_at_all_locations": true,
                    "item_variation_data": {
                        "item_id": "JOIBESOPRL42QUMKXR57SEQA",
                        "name": "Item for sale",
                        "ordinal": 0,
                        "pricing_type": "FIXED_PRICING",
                        "price_money": {
                            "amount": 1999,
                            "currency": "USD"
                        },
                        "sellable": true,
                        "stockable": true
                    }
                }
            ],
            "product_type": "REGULAR",
            "image_ids": [
                "XOMHAUUSKU2XWHRQMXU22LXP"
            ]
        }
    },
    "id_mappings": [
        {
            "client_object_id": "#item",
            "object_id": "JOIBESOPRL42QUMKXR57SEQA"
        },
        {
            "client_object_id": "#variation",
            "object_id": "7X7ZFRSJAPOIJOYQ2MVGZFXL"
        }
    ]
}

The specified image object (XOMHAUUSKU2XWHRQMXU22LXP) is now attached to the newly created item (JOIBESOPRL42QUMKXR57SEQA) as the sole element of the image_ids list.

Link to section
Attach an uploaded image to an existing item

Now, try to attach another uploaded image object (XOGYYRVXFY7YSUFQG2UOTGUA) to the previously created item (JOIBESOPRL42QUMKXR57SEQA) by appending the new image ID to the item's image_ids list.

When calling the UpsertCatalogObject endpoint to update a catalog object, you must provide in the input all the required information about the object to be updated, even if some aren't changed. One way to do this is to retrieve the catalog item first, make necessary changes to it, and then supply the modified item in the UpsertCatalogObject request to complete the update.

Link to section
Request

In this example, you only need to change the image_ids list by appending the new image object ID to it.

Upsert Catalog Object
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
  • 38
  • 39
  • 40
  • 41
  • 42
  • 43
  • 44
  • 45
curl https://connect.squareupsandbox.com/v2/catalog/object \
  -X POST \
  -H 'Square-Version: 2023-08-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "object": {
      "type": "ITEM",
      "id": "JOIBESOPRL42QUMKXR57SEQA",
      "version": 1638936862829,
      "is_deleted": false,
      "present_at_all_locations": true,
      "item_data": {
        "name": "Item with images",
        "description": "test item to attach images to",
        "variations": [
          {
            "type": "ITEM_VARIATION",
            "id": "7X7ZFRSJAPOIJOYQ2MVGZFXL",
            "version": 1638936862829,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_variation_data": {
              "item_id": "JOIBESOPRL42QUMKXR57SEQA",
              "name": "Item for sale",
              "ordinal": 0,
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 1999,
                "currency": "USD"
              },
              "sellable": true,
              "stockable": true
            }
          }
        ],
        "product_type": "REGULAR",
        "image_ids": [
          "XOMHAUUSKU2XWHRQMXU22LXP",
          "XOGYYRVXFY7YSUFQG2UOTGUA"
        ]
      }
    }
  }'
Try in API Explorer

Link to section
Response

If successful, the request returns a response similar to the following:

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
  • 38
  • 39
  • 40
  • 41
  • 42
  • 43
{
    "catalog_object": {
        "type": "ITEM",
        "id": "JOIBESOPRL42QUMKXR57SEQA",
        "updated_at": "2021-12-15T04:47:58.833Z",
        "created_at": "2021-12-15T04:14:22.829Z",
        "version": 1638938878833,
        "is_deleted": false,
        "present_at_all_locations": true,
        "item_data": {
            "name": "Item with images",
            "description": "test item to attach images to",
            "variations": [
                {
                    "type": "ITEM_VARIATION",
                    "id": "7X7ZFRSJAPOIJOYQ2MVGZFXL",
                    "updated_at": "2021-12-15T04:47:58.833Z",
                    "created_at": "2021-12-15T04:14:22.829Z",
                    "version": 1638938878833,
                    "is_deleted": false,
                    "present_at_all_locations": true,
                    "item_variation_data": {
                        "item_id": "JOIBESOPRL42QUMKXR57SEQA",
                        "name": "Item for sale",
                        "ordinal": 0,
                        "pricing_type": "FIXED_PRICING",
                        "price_money": {
                            "amount": 1999,
                            "currency": "USD"
                        },
                        "sellable": true,
                        "stockable": true
                    }
                }
            ],
            "product_type": "REGULAR",
            "image_ids": [
                "XOMHAUUSKU2XWHRQMXU22LXP",
                "XOGYYRVXFY7YSUFQG2UOTGUA"
            ]
        }
    }
}

The response shows that the new image object (XOGYYRVXFY7YSUFQG2UOTGUA) is added to the end of the image_ids list. The update operation doesn't change the primary image of the item. You could add the new image object to the head of the image_ids list, thereby updating the item's primary image, as well.

Link to section
Reorder the image list on an item

When the image_ids list already has more than one elements, you can reorder the image_ids list on an item or variation by calling the UpsertCatalogObject endpoint on the item while shuffling the elements of the image_ids list in the desired order.

Using the previous example, you can rotate the image_ids list of:

  • 1
    "image_ids": ["XOMHAUUSKU2XWHRQMXU22LXP", "XOGYYRVXFY7YSUFQG2UOTGUA"]

by calling UpsertCatalogObject again, while specifying the image_ids list of:

  • 1
    "image_ids": ["XOGYYRVXFY7YSUFQG2UOTGUA", "XOMHAUUSKU2XWHRQMXU22LXP"]

in the input. The reordering makes the image (XOGYYRVXFY7YSUFQG2UOTGUA) the primary image of the item.

Link to section
Detach an image from an attached object

To detach an image from an attached object, you remove the image object ID from the image_ids list of the attached catalog object, when calling the UpsertCatalogObject endpoint.

Setting the image_ids list to an empty list or null in the call removes all the images attached to the object. Detached image objects aren't deleted from the catalog.

If you delete an image object attached to a catalog object by calling the DeleteCatalogObject endpoint on the image object ID, the deleted image object ID is also removed from the image_ids list of the catalog object. The deleted image is detached from the catalog object.

On this page