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}

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

{
"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"
}
}
}
--boundary
Content-Disposition: form-data; name="image"; filename="Coffee.jpg"
Content-Type: image/jpeg

{ACTUAL_IMAGE_BYTES}
--boundary

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
idempotency_key
string

Required

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
image
Catalog​Object

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

object_id
string

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.

Response Fields

Name Description
errors
Error [ ]

Information on any errors encountered.

image
Catalog​Object

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

Examples

You are viewing an old version of the API
POST /v2/catalog/images
cURL
  • cURL
  • Ruby
  • Python
curl https://connect.squareup.com/v2/catalog/images \
  -X POST \
  -H 'Square-Version: 2019-11-20' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -F 'file=@/local/path/to/file.jpg' \
  -F 'request={
    "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?