Upload a product image

POST https://api.squarespace.com/{api-version}/commerce/products/{id}/images

Uploads an image for a product. If a product doesn’t have an existing image, then the first uploaded image is used as the primary image for the product.

A successful request creates a ProductImage subresource of the Product. Read the Overview to learn more about these resources.

While smaller images often finish processing within seconds, larger images may take more time. To check the upload status, poll the Product image upload status endpoint at a moderate interval that’s suitable for your application’s needs.

Note: Uploads resulting in an error may be retried, but it’s strongly encouraged that these uploads are removed from the system as they may render on the site as placeholder images. Use the Delete a product image endpoint before retrying an image upload.

Image and image file guidelines

• Dimensions of the image itself must be less than 60MP.
• File type must be either a JPEG, JPG, PNG, or GIF and less than 20MB, though images that are less than 500KB are recommended.
• Filename should follow Squarespace’s alt text best practices. The endpoint uses the uploaded filename for the image’s alt text as well as its URL — two major factors that impact site SEO. To update the alt text after a file upload, use the Update product image endpoint.

Parameters

If needed, see the "Related endpoints" section to learn how to retrieve resource ids.

{api-version} string
required

See the Products API Overview page for the current API version.

{id} string
required

Specifies the Product that will own the ProductImage.

Request example

This endpoint uses multipart/form-data to upload the image, and the name and filename parameters used in the form-data Content-Disposition header must be specified for a successful request. Visit MDN docs to learn more about multipart/form-data and the Content-Disposition header.

curl "https://api.squarespace.com/1.0/commerce/products/123/images" \
  -i \
  -H "Authorization: Bearer YOUR_API_KEY_OR_OAUTH_TOKEN" \
  -H "User-Agent: YOUR_CUSTOM_APP_DESCRIPTION" \
  -H "Content-Type: multipart/form-data" \
  -X POST \
  # The cURL flag below automatically sets `name` to "file"
  # and `filename` to the specified filename.
  # If not using cURL, it’s strongly recommended to use a library that supports
  # `multipart/form-data` requests so the parameters below can be specified:
  #     `name` = "file"
  #     `filename` = "YOUR_FILENAME"
  # If `name` is not set to "file" and/or `filename` is not specified then the request fails.
  -F file=@steak.png

Response example

A response to a successful request generates a JSON response containing the unique id of the ProductImage.

Note: For easier reference between the response field and description, a comment was added in the example, though this makes the JSON invalid.

{
  // Unique ProductImage id.
  "imageId": "5ed539bc8367410cdc0c984a"
}

Status codes and error conditions

202 ACCEPTED

The request was successful and the uploaded image is being processed. The response contains the id of the created ProductImage resource.

400 BAD REQUEST

Type: INVALID_REQUEST_ERROR

Subtype: null
The request body does not conform to specification.

404 NOT FOUND

Type: INVALID_REQUEST_ERROR

Subtype: INVALID_ARGUMENT
The requested Product was not found.

409 CONFLICT

Type: CONFLICT

Subtype: IMAGE_LIMIT_REACHED
The specified Product has reached its limit of 100 images.

Related endpoints

To retrieve ids for Products, use these suggested endpoints:

• Retrieve all products
• Retrieve specific products