Work with Images
This is pre-release documentation for an API in public beta and is subject to change.
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 Square 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_idslist of an image-supporting catalog object.
The image is unattached if its object ID is not a member of the
image_idslist 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_idslist of the image-supporting object. To do this using the Catalog API, call the UpsertCatalogObject endpoint, specifying an updated
image_idslist, along with other unchanged attribute values. For Square API versions prior to 2021-12-15, the
CatalogObjectreverts to the legacy
image_idto hold the latest attached single
Detach an image from an image-supporting object by removing the ID of the encapsulating image object from the
image_idslist of the linked image-supporting catalog object. To do this using the Catalog API, call the UpsertCatalogObject endpoint, along with the updated
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
include_related_objects. Alternatively, you can call RetrieveCatalogObject or BatchRetrieveCatalogObjects while enabling
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:
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.