Catalog API

Upload and Attach an Image

Uploading an image and attaching it to an item, item variation, or category involves calling the CreateCatalogImage and UpsertCatalogObject endpoints.

In general, the process can proceed in following scenarios:

  • Upload an image file to the catalog.

  • Attach an uploaded image to an existing item, variation, or category.

  • Attach an uploaded image to a new item, variation, or category.

Before you start Permalink Get a link to this section

  • You can only upload images in the JPEG, PJPEG, PNG, or GIF format to a Square catalog.

  • To upload an image to a Square catalog, you must call CreateCatalogImage using the REST API or the Square SDK for Ruby, Python, .NET, or Java.

    The CreateCatalogImage request requires the following additional headers to upload a catalog image:

    -H 'Content-Disposition: form-data; name="name"; filename="name.jpg"' \
    -H 'Content-Type: image/JPEG' \
    

    Some tools, such cURL commands, automatically include these headers behind the scenes. Others rely on you to set them explicitly.

Upload an image to a catalog Permalink Get a link to this section

To upload a catalog image, call CreateCatalogImage with the local path of the image file. The request requires that you supply a unique idempotency_key value.

In the Square catalog, an image is represented by a CatalogImage instance. To create such an instance, you must set the CatalogObject type to IMAGE and configure the image_data property to specify required or optional metadata about the image, including the name and caption of the image.

The following REST API example in cURL shows how to call the CreateCatalogImage endpoint to upload an image file named Lions_on_roads.jpg:

Request Permalink Get a link to this section

curl https://connect.squareup.com/v2/catalog/images \
  -v -X POST \
  -H 'Square-Version: 2020-08-12' \
  -H 'Authorization: Bearer <SQUARE_PERSON_ACCESS_SECRET>' \
  -H 'Accept: application/json' \
  -H 'Content-Disposition: form-data; name=“lions”; filename=“/loca/path/to/Lions_on_roads.jpg”' \
  -H ‘Content-Type: image/JPEG’ \
  -F 'file=@Lions_on_roads.jpg' \
  -F 'request={
    "idempotency_key": "7cb92507-76c6-43a2-94c0-1b2a092ada6b",
    "image": {
      "id": "#lions",
      "type": "IMAGE",
      "image_data": {
        "caption": "Lions by the road"
      }
    }
  }’

The CreateCatalogImage request has a multi-part payload. In cURL, you use -F parameters to describe the parts. To specify the local path to the image file, use the Content-Disposition header.

Response Permalink Get a link to this section

A successful call returns a CatalogImage object that includes the image data and a Square-generated image URL used to access the stored image file:

{
  "image": {
    "type": "IMAGE",
    "id": "7WWYBOW5AYLEWFW62HQX7EP4",
    "updated_at": "2020-08-26T16:37:03.648Z",
    "version": 1598459823648,
    "is_deleted": false,
    "present_at_all_locations": true,
    "image_data": {
      "name": "Lions",
      "url": "https://square-staging.s3.amazonaws.com/files/40f41f96dc5f4717cf8a14fce764b945104adc1e/original.jpeg",
      "caption": "Lions by the road"
    }
  }
}

Make note of the image ID value. You need to use it to reference this uploaded image, for example, when attaching the image to an existing item.

Attach an uploaded image to an existing item Permalink Get a link to this section

Suppose you have created an item of the APPOINTMENTS_SERVICE product type and this service item has an ID of BDWYGZO5QQWWEVFV6PAEP3BS. To attach the uploaded image ("id":"7WWYBOW5AYLEWFW62HQX7EP4" created previously), call the UpsertCatalogObject (or its batch variant to attach multiple images to one or more existing items) to set the image ID on the item's image_id property.

Request Permalink Get a link to this section

The following cURL request provides a working example to attach the image (7WWYBOW5AYLEWFW62HQX7EP4) to an existing service item (BDWYGZO5QQWWEVFV6PAEP3BS):

curl https://connect.squareup.com/v2/catalog/object \
  -X POST \
  -H 'Square-Version: 2020-08-12' \
  -H 'Authorization: Bearer <SQUARE_PERSON_ACCESS_SECRET>' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "7d99e1f2-1937-438a-ba7f-e8af982dd2b0",
    "object": {
      "id": "BDWYGZO5QQWWEVFV6PAEP3BS",
      "type": "ITEM",
      "image_id": "7WWYBOW5AYLEWFW62HQX7EP4",
      "version": 1598474076346,
      "item_data": {
        "name": "adventure",
        "product_type": "APPOINTMENTS_SERVICE",
        "skip_modifier_screen": false,
        "variations": [
          {
            "id": "PRAVBIFA4IDWI3IPO6KQVV2B",
            "type": "ITEM_VARIATION",
            "version": 1598474076346,
            "item_variation_data": {
              "name": "8-day explore",
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 250000,
                "currency": "USD"
              },
              "item_id": "BDWYGZO5QQWWEVFV6PAEP3BS"
            }
          }
        ]
      }
    }
  }’

When setting the item's image_id attribute, make sure to specify other required properties, including version and item_data, to match the existing property values.

Response Permalink Get a link to this section

If successful, the request returns a response similar to the following:

{
  "catalog_object": {
    "type": "ITEM",
    "id": "BDWYGZO5QQWWEVFV6PAEP3BS",
    "updated_at": "2020-08-27T03:43:15.993Z",
    "version": 1598499795993,
    "is_deleted": false,
    "present_at_all_locations": true,
    "image_id": "7WWYBOW5AYLEWFW62HQX7EP4",
    "item_data": {
      "name": "adventure",
      "variations": [
        {
          "type": "ITEM_VARIATION",
          "id": "PRAVBIFA4IDWI3IPO6KQVV2B",
          "updated_at": "2020-08-26T20:34:36.346Z",
          "version": 1598474076346,
          "is_deleted": false,
          "present_at_all_locations": true,
          "item_variation_data": {
            "item_id": "BDWYGZO5QQWWEVFV6PAEP3BS",
            "name": "8-day explore",
            "ordinal": 0,
            "pricing_type": "FIXED_PRICING",
            "price_money": {
              "amount": 250000,
              "currency": "USD"
            }
          }
        }
      ],
      "product_type": "APPOINTMENTS_SERVICE",
      "skip_modifier_screen": false
    }
  }
}

Attach an uploaded image to a new item Permalink Get a link to this section

You can call the Catalog API to create a new item and attach an uploaded image to it at the same time. This also involves calling the UpsertCatalogObject endpoint, as illustrated in the following cURL example:

Request Permalink Get a link to this section

curl https://connect.squareup.com/v2/catalog/object \
  -X POST \
  -H 'Square-Version: 2020-08-26' \
  -H 'Authorization: Bearer <SQUARE_PERSON_ACCESS_SECRET>' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "bc5f824d-9233-4510-bd12-62a499adb1d2",
    "object": {
      "id": "#item",
      "type": "ITEM",
      "item_data": {
        "name": "adventure",
        "product_type": "APPOINTMENTS_SERVICE",
        "variations": [
          {
            "id": "#variation",
            "type": "ITEM_VARIATION",
            "item_variation_data": {
              "name": "8-day explore",
              "price_money": {
                "amount": 250000,
                "currency": "USD"
              },
              "pricing_type": "FIXED_PRICING"
            }
          }
        ]
      },
      "image_id": "7WWYBOW5AYLEWFW62HQX7EP4"
    }
  }'

Attaching an uploaded image to a new item is similar to attaching an uploaded image to an existing item.

Response Permalink Get a link to this section

{
  "catalog_object": {
    "type": "ITEM",
    "id": "I4BKTYZ3J4JF3PRWVAARFXOG",
    "updated_at": "2020-08-31T18:34:03.027Z",
    "version": 1598898843027,
    "is_deleted": false,
    "present_at_all_locations": true,
    "image_id": "7WWYBOW5AYLEWFW62HQX7EP4",
    "item_data": {
      "name": "adventure",
      "variations": [
        {
          "type": "ITEM_VARIATION",
          "id": "K54S22RNPGZWD4NAMZA5NKNP",
          "updated_at": "2020-08-31T18:34:03.027Z",
          "version": 1598898843027,
          "is_deleted": false,
          "present_at_all_locations": true,
          "item_variation_data": {
            "item_id": "I4BKTYZ3J4JF3PRWVAARFXOG",
            "name": "8-day explore",
            "ordinal": 0,
            "pricing_type": "FIXED_PRICING",
            "price_money": {
              "amount": 250000,
              "currency": "USD"
            }
          }
        }
      ],
      "product_type": "APPOINTMENTS_SERVICE"
    }
  },
  "id_mappings": [
    {
      "client_object_id": "#item",
      "object_id": "I4BKTYZ3J4JF3PRWVAARFXOG"
    },
    {
      "client_object_id": "#variation",
      "object_id": "K54S22RNPGZWD4NAMZA5NKNP"
    }
  ]
}