Applies to: Catalog API
Learn how to upload images to a Square catalog and attach them to supporting objects in the catalog.
Uploading an image file to the catalog involves creating a CatalogImage object, specifying the local path to the image file and, optionally, the name or caption of the image. When creating a CatalogImage object, you can also specify the ID of the catalog object you are attaching the image to. This way you can manage to upload an image and attach the uploaded image object to an image-attachable catalog object in a single operation.
To create a catalog image, call the CreateCatalogImage endpoint. This is different from creating any other types of CatalogObject where you call the UpsertCatalogObject or BatchUpsertCatalogObjects endpoint.
You can attach an image object to any of the following catalog objects:
Your application business logic should let a seller upload and attach images with these considerations:
- Attach during upload - In the
CreateCatalogImagerequest, set theobject_idparameter to the ID of the catalog object you're attaching the image to. If the parameter isn't set, the image is unattached when created. - Attach after upload - To attach the image after it's created, use
UpsertCatalogObjectorBatchUpsertCatalogObjectsto update theimage_idslist property of the catalog object you're attaching the image to. - Attach to multiple objects - An image that's already attached to one object can also be attached to others. Also, multiple images can be attached to the same catalog object using the
image_idslist. - Set a primary image - To make an image the primary one, set its ID as the first element in the
image_idslist and setis_primarytotrue. For API versions2021-12-15and later, the default foris_primaryisfalse; for earlier versions, it'strue. The primary image is displayed in Square first-party products, such as Square Point of Sale and Square Online. - Duplicate an image check - If you upload an already existing image, no new image is created. The response includes the existing image object.
The following example shows how to call the CreateCatalogImage endpoint to upload a local image file (image_example_1.png) as a CatalogImage object and attach the resulting image object to an existing CatalogItem (GQKOOBBI4PE3B7MLXDQ7YUSM) that has one variation and no attached images yet:
Create catalog image
The following example shows how to call the CreateCatalogImage endpoint to upload a local image file named image_example.png as an unattached CatalogImage object:
Create catalog image
The filename parameter can be an absolute path to the image file, such as "/myapp/data/image_example.png". If the folder path (such as "/myapp/data/") isn't given, the default folder is the working directory where you invoke the command.
The image object is an instance of CatalogImage, also known as an IMAGE type of CatalogObject. For the image object, you must set only the image-specific data on the image_data attribute of the CatalogObject.
The resulting image object is unattached because the request body doesn't specify the object_id attribute.
To attach an image to a CatalogItem, CatalogItemVariation, CatalogCategory, or CatalogModifierList, add the ID of the image to the image_ids list property of the catalog object.
Did you know?
A single image can be attached to many catalog objects.
The following example retrieves the image to be attached and the catalog item to attach it to. The BatchRetrieveObjects endpoint is used. The catalog item is then modified with the updated image_ids property.
The following example retrieves an image (BQC5NCY7VIKL6WQN5MOBJL3V) and a catalog item (GQKOOBBI4PE3B7MLXDQ7YUSM):
Batch retrieve catalog objects
To attach the image to the catalog item, the CatalogItem is updated to add an image_ids property with the ID of the image to attach.
Upsert catalog object
When multiple images are attached to a catalog object, the first element of the image_ids list is the primary image of the object. A primary image is displayed when the image-supporting object is processed in Square Point of Sale and the Square Online Store.
When another image is attached to the catalog object using Square API version 2021-12-15 or later, the new image object ID is appended to the image_ids list by default. To attach the new image as a primary image, set the is_primary input parameter to true when calling CreateCatalogImage, as shown in the following example:
Create catalog image