• Example searches: “transaction”, “CreateOrder”, “/v2/locations”, “inventory”, “delete customer”

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

POST /v2/catalog/images

Uploads an image file to be represented by a CatalogImage object that can be linked to an existing CatalogObject instance.

The resulting CatalogImage is unattached to any CatalogObject if the object_id is not specified.

This CreateCatalogImage endpoint 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.

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

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

image
CatalogObject

Required

The new CatalogObject of the IMAGE type, namely, a CatalogImage object, to encapsulate the specified image file.

is_primary
boolean

Beta

If this is set to true, the image created will be the primary, or first image of the object referenced by object_id. If the CatalogObject already has a primary CatalogImage, setting this field to true will replace the primary image. If this is set to false and you use the Square API version 2021-12-15 or later, the image id will be appended to the list of image_ids on the object.

With Square API version 2021-12-15 or later, the default value is false. Otherwise, the effective default value is true.

Response Fields

Name Description
errors
Error [ ]

Any errors that occurred during the request.

image
CatalogObject

The newly created CatalogImage including a Square-generated URL for the encapsulated image file.

Examples

You are viewing an old version of the API
POST /v2/catalog/images
cURL
  • cURL
  • Ruby
  • Python
  • C#
  • Java
  • PHP
  • Node.js
curl https://connect.squareup.com/v2/catalog/images \
  -X POST \
  -H 'Square-Version: 2022-09-21' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Accept: application/json' \
  -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"
      }
    }
  }'
Response JSON
{
  "image": {
    "id": "KQLFFHA6K6J3YQAQAWDQAL57",
    "type": "IMAGE",
    "image_data": {
      "url": "https://...",
      "caption": "A picture of a cup of coffee"
    }
  }
}

Error Descriptions

400 Bad request GENERIC_DECLINE

Square received a decline without any additional information. If the payment information seems correct, the buyer can contact their issuer to ask for more information.

>
400 Bad request
{
  "errors": [
    {
      "code": "GENERIC_DECLINE",
      "category": "PAYMENT_METHOD_ERROR"
    }
  ]
}