Work with Images

Applies to: Catalog API

Learn about uploading and attaching images to your product catalog with the Catalog API.

Images are compelling and enable rich online store experiences. You can attach one or more images to Item, Item Variation, Catalog Category, and Modifier List objects. The images provide visual representations of products for sale and services for hire by a seller.

When you upload an image and attach it to an item such as a Catalog Category, it appears in the Square Dashboard as shown in the following image:

The Catalog API performs the same operation as a seller dragging an image onto the dialog.

• 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 a catalog 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.

The following tasks manage the lifecycle of a catalog image:

• Upload an image - Use the CreateCatalogImage endpoint to upload an image file. It's stored as a CatalogImage object. An image is attached if its ID is in the image_ids list of a catalog object. Otherwise, it's unattached.
• Attach an image - Add the image's ID to the image_ids list of a catalog object using the UpsertCatalogObject endpoint.
• Detach an image - Remove the image's ID from the image_ids list using the UpsertCatalogObject endpoint.
• Update an image file - Use the UpdateCatalogImage endpoint with the image object ID and new image file path.
• Update image metadata - Update metadata like name and caption using the UpsertCatalogObject endpoint.
• Retrieve attached images - Use the SearchCatalogObjects, RetrieveCatalogObject, or BatchRetrieveCatalogObjects endpoints with the include_related_objects property enabled.
• Remove an image - Call the DeleteCatalogObject endpoint with the image object ID to delete it.

• Upload and Attach Images
• Manage Images in a Square Catalog