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: