Work with Images

Applies to: Catalog API

Learn about uploading and attaching images to your product catalog.

Images are compelling and enable rich online store experiences. For certain types of Square catalog objects, you can attach one or more images to the objects to provide visual representations of products for sale or services for hire by a seller. To do so programmatically, you can use the Catalog API.

Generally speaking, attaching images to an object and subsequently managing the images involves the following tasks, not necessarily in the order specified:

• Upload an image file into a Square seller account as either unattached or attached. To do this using the Catalog API, call the CreateCatalogImage endpoint.
  • The uploaded image file is encapsulated as a CatalogImage object.
  • The image is attached if the image object ID is a member of the image_ids list of an image-supporting catalog object.
  • The image is unattached if its object ID isn't a member of the image_ids list of any image-supporting catalog object.
• Attach an image object (encapsulating an image file) to an image-supporting catalog object by adding the image object ID to the image_ids list of the image-supporting object. To do this using the Catalog API, call the UpsertCatalogObject endpoint, specifying an updated image_ids list, along with other unchanged attribute values. For Square API versions prior to 2021-12-15, the CatalogObject reverts to the legacy image_id to hold the latest attached single CatalogImage object.
• Detach an image from an image-supporting object by removing the ID of the encapsulating image object from the image_ids list of the linked image-supporting catalog object. To do this using the Catalog API, call the UpsertCatalogObject endpoint, along with the updated image_ids list.
• Update an uploaded image object with a different image file. To do this using the Catalog API, call the UpdateCatalogImage endpoint, specifying the image object ID and the new image file path.
• Update metadata (such as image name and caption) of an uploaded image. To do this using the Catalog API, call the UpsertCatalogObject endpoint on the uploaded image object, specifying the updated values of the affected attributes along with other unchanged attribute values.
• Retrieve image objects attached to image-supporting catalog objects. To do so, call the SearchCatalogObjects specifying targeted object types as ITEM, ITEM_VARIATION, CATEGORY or MODIFIER_LIST while enabling include_related_objects. Alternatively, you can call RetrieveCatalogObject or BatchRetrieveCatalogObjects while enabling include_related_objects.
• Remove an image from a seller account to free up the resource. To do this, call the DeleteCatalogObject endpoint, specifying the ID of the encapsulating image object.

Image support is restricted to certain types of catalog objects and there are limits to how large an image can be, the number of images that can be attached to an object of the supported types, the number of unattached images per seller account, and the number of images per seller account.

The following types of objects can have an image object attached:

• Item
• Item variation
• Category
• Modifier list

The image number, size, and format limitations are as follows:

• An image can use the JPEG, PJPEG, PNG, or GIF format.
• An image file cannot be larger than 250 MB.
• There can be no more than 250 images attached to an image-supporting object.
• There can be no more than 10,000 unattached images per Square account.
• There can be no more than 5 million images per Square account.