You are viewing an old version of the API
Create catalog image

Upload an image file to create a new CatalogImage for an existing CatalogObject.

Images can be uploaded and linked in this request or created independently (without an object assignment) and linked to a CatalogObject at a later time.

CreateCatalogImage accepts HTTP multipart/form-data requests with a JSON part and an image file part in JPEG, PJPEG, PNG, or GIF format. The maximum file size is 15MB. The following is an example of such an HTTP request:

POST /v2/catalog/images
Accept: application/json
Content-Type: multipart/form-data;boundary="boundary"
Square-Version: XXXX-XX-XX
Authorization: Bearer {ACCESS_TOKEN}

Content-Disposition: form-data; name="request"
Content-Type: application/json

"object_id": "ND6EA5AAJEO5WL3JNNIAQA32",
"caption":"A picture of a cup of coffee"
Content-Disposition: form-data; name="image"; filename="Coffee.jpg"
Content-Type: image/jpeg


Additional information and an example cURL request can be found in the Create a Catalog Image recipe.

Required permissions ITEMS_WRITE

Request Body

Name Description


A unique string that identifies this CreateCatalogImage request. Keys can be any valid string but must be unique for every CreateCatalogImage request.

See Idempotency keys for more information.

Min Length 1

Unique ID of the CatalogObject to attach to this CatalogImage. Leave this field empty to create unattached images, for example if you are building an integration where these images can be attached to catalog items at a later time.


The new IMAGE-type CatalogObject to be attached to this CatalogImage. If the CatalogObject already has a CatalogImage, this call will overwrite it.

Response Fields

Name Description
Error [ ]

Information on any errors encountered.


The newly created CatalogImage including a Square-generated URL for each image.


You are viewing an old version of the API
POST /v2/catalog/images
  • cURL
  • Ruby
  • Python
  • C#
  • Java
curl \
  -X POST \
  -H 'Square-Version: 2020-01-22' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "528dea59-7bfb-43c1-bd48-4a6bba7dd61f86",
    "object_id": "ND6EA5AAJEO5WL3JNNIAQA32",
    "image": {
      "id": "#TEMP_ID",
      "type": "IMAGE",
      "image_data": {
        "caption": "A picture of a cup of coffee"

Share Feedback

Thanks for visiting the Square API documentation. What's on your mind?