Product Images API

Upload, list, describe, and delete images for a product. Image uploads use
multipart/form-data.

Endpoints

• List Product Images - GET /api/v1/products/{product_id}/images/
• Upload Product Images - POST /api/v1/products/{product_id}/images/
• Update Product Image - PUT /api/v1/products/{product_id}/images/{image_id}/
• Delete Product Image - DELETE /api/v1/products/{product_id}/images/{image_id}/

List Product Images

Retrieve all images for a product. This endpoint is not paginated.

Endpoint: GET /api/v1/products/{product_id}/images/

Scope Required: products:read

Request

curl -X GET "https://studio.easel.engineering/api/v1/products/pro_d0b6fmv28q6vn14peun0/images/" \
  -H "Authorization: Bearer your_api_key_here"

Response

Status: 200 OK

{
  "data": [
    {
      "id": "img_d0b6fmv28q6vn14peun0",
      "url": "/images/img_d0b6fmv28q6vn14peun0-large.webp",
      "alt_text": "Front of the t-shirt",
      "width": 1200,
      "height": 1200,
      "format": "webp",
      "created_at": "2023-01-01T10:00:00Z",
      "external_source": null,
      "external_id": null,
      "taken_down_at": null
    }
  ]
}

The url is relative to the storefront origin.

Upload Product Images

Upload one or more images for a product. Send the images as files in a
multipart/form-data body. Every file part is stored, so you can include
several images in a single request.

Endpoint: POST /api/v1/products/{product_id}/images/

Scope Required: products:write

Limits

• The total request body must be 50 MiB or smaller.
• Images must be no larger than 8192 pixels in either dimension. Larger
  images are rejected.
• Supported formats depend on the image decoder. Common web formats such as
  JPEG, PNG, GIF, and WebP are accepted.

Uploaded images are downscaled and re-encoded as WebP, which keeps
transparency, and report a format of webp. The derived files are named
<image_id>-<size>.webp, for example img_d0b6fmv28q6vn14peun0-large.webp.
Each image also has a JPEG copy, <image_id>-share.jpeg, up to 1200 pixels on
its longest side, for email clients and link previews that can't show WebP.
Images uploaded before WebP report jpeg or png until Easel converts them.
Photos are turned upright using their EXIF orientation, so a phone photo taken
sideways is stored the right way up.

Form Fields

Request

curl -X POST "https://studio.easel.engineering/api/v1/products/pro_d0b6fmv28q6vn14peun0/images/" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Idempotency-Key: unique-request-id-12345" \
  -F "file=@front.jpg" \
  -F "file=@back.jpg"

Response

Status: 201 Created

{
  "data": [
    {
      "id": "img_d0b6fmv28q6vn14peun0",
      "url": "/images/img_d0b6fmv28q6vn14peun0-large.webp",
      "alt_text": "",
      "width": 1200,
      "height": 1200,
      "format": "webp",
      "created_at": "2023-01-01T10:00:00Z",
      "external_source": null,
      "external_id": null,
      "taken_down_at": null
    }
  ]
}

Error Responses

Invalid multipart form

Status: 400 Bad Request

{
  "error": "Invalid input",
  "code": "INVALID_FIELD"
}

Request too large

Status: 413 Request Entity Too Large

{
  "error": "Request body is too large",
  "code": "REQUEST_TOO_LARGE"
}

Image refused

A file Easel removed as illegal can't be uploaded to any store.

Status: 422 Unprocessable Entity

{
  "error": "The image can't be uploaded",
  "code": "INVALID_FIELD"
}

Update Product Image

Set an image's alt text, which describes it for screen readers and search
engines. The storefront's product page uses it, and falls back to the
product's name for an image without any. Translate it into the site's other
languages with the Translations API.

Endpoint: PUT /api/v1/products/{product_id}/images/{image_id}/

Scope Required: products:write

Request Body

Request

curl -X PUT "https://studio.easel.engineering/api/v1/products/pro_d0b6fmv28q6vn14peun0/images/img_d0b6fmv28q6vn14peun0/" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"alt_text": "Front of the t-shirt"}'

Response

Status: 200 OK

The updated image.

{
  "id": "img_d0b6fmv28q6vn14peun0",
  "url": "/images/img_d0b6fmv28q6vn14peun0-large.webp",
  "alt_text": "Front of the t-shirt",
  "width": 1200,
  "height": 1200,
  "format": "webp",
  "created_at": "2023-01-01T10:00:00Z",
  "external_source": null,
  "external_id": null,
  "taken_down_at": null
}

Error Responses

Alt text too long

Status: 400 Bad Request

{
  "error": "Invalid input",
  "code": "INVALID_FIELD"
}

Image not found, or not on this product

Status: 404 Not Found

{
  "error": "Resource not found",
  "code": "NOT_FOUND"
}

Delete Product Image

Delete an image from a product.

Endpoint: DELETE /api/v1/products/{product_id}/images/{image_id}/

Scope Required: products:write

Request

curl -X DELETE "https://studio.easel.engineering/api/v1/products/pro_d0b6fmv28q6vn14peun0/images/img_d0b6fmv28q6vn14peun0/" \
  -H "Authorization: Bearer your_api_key_here"

Response

Status: 204 No Content

Error Responses

Image not found

Status: 404 Not Found

{
  "error": "Resource not found",
  "code": "NOT_FOUND"
}

Image Object

Fields

Takedowns

Easel hosts your store's content, so under the EU Digital Services Act its
staff may take an image down that's illegal or against Easel's terms (see
Moderation). A taken-down image stays on
its product, with taken_down_at set, but isn't served at any size, so
its url stops loading, on the storefront too. Delete it, or upload
another in its place. The statement of reasons was emailed to the
store's owners, and the dashboard keeps it under Settings › Activity ›
Easel decisions; the activity log's taken_down event, on the store with
part image, names the category in reason.