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 theimage_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 theUpsertCatalogObject
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.