Product Image

Product images could well be the single most important design aspect of any store. Without the ability to touch, hold, smell, taste or otherwise handle the products they are interested in, potential customers have only images to interact with.

The product images have the following restrictions:

• Must weight less than 10MB
• Must be in one of the following formats: .gif, .jpg, .png, .webp

Properties

Property	Explanation
id	The unique numeric identifier for the Product Image
product_id	The id of the product associated with the image
src	URL of the product image
position	Number indicating the position of the image in the product's image list. 1 is the first and the main product image
created_at	Date when the Product Image was created in ISO 8601 format
updated_at	Date when the Product Image was last updated in ISO 8601 format
alt	Image alt text helps search engines like Google understand when to show the image in a search result
store_media_uuid	UUID of the Store Media asset backing this image, when the image was created/updated from a Store Media. null for images uploaded via src/attachment. Optional input on the POST/PUT endpoints

Endpoints

GET /products/{product_id}/images

Receive a list of all Product Images for a given product.

Parameter	Explanation
since_id	Restrict results to after the specified ID
src	Show Product Images with a given URL
position	Show Product Images at a given position
page	Page to show
per_page	Amount of results
fields	Comma-separated list of fields to include in the response

GET /products/1234/images

HTTP/1.1 200 OK

[
  {
    "id": 101,
    "src": "http://d26lpennugtm8s.cloudfront.net/stores/001/234/products/servine-640-0.jpg",
    "position": 1,
    "product_id": 1234,
    "created_at": "2013-01-03T09:11:51-03:00",
    "updated_at": "2013-03-11T09:14:11-03:00"
  },
  {
    "id": 112,
    "src": "http://d26lpennugtm8s.cloudfront.net/stores/001/234/products/onyx-640-0.jpg",
    "position": 2,
    "product_id": 1234,
    "created_at": "2013-01-03T09:11:51-03:00",
    "updated_at": "2013-03-11T09:14:11-03:00"
  },
  {
    "id": 123,
    "src": "http://d26lpennugtm8s.cloudfront.net/stores/001/234/products/stoutland-640-0.jpg",
    "position": 3,
    "product_id": 1234,
    "created_at": "2013-01-03T09:11:51-03:00",
    "updated_at": "2013-03-11T09:14:11-03:00"
  }
]

GET /product/1234/images?since_id=105

HTTP/1.1 200 OK

[
  {
    "id": 112,
    "src": "http://d26lpennugtm8s.cloudfront.net/stores/001/234/products/onyx-640-0.jpg",
    "position": 2,
    "product_id": 1234,
    "created_at": "2013-01-03T09:11:51-03:00",
    "updated_at": "2013-03-11T09:14:11-03:00"
  },
  {
    "id": 123,
    "src": "http://d26lpennugtm8s.cloudfront.net/stores/001/234/products/stoutland-640-0.jpg",
    "position": 3,
    "product_id": 1234,
    "created_at": "2013-01-03T09:11:51-03:00",
    "updated_at": "2013-03-11T09:14:11-03:00"
  }
]

GET /products/{product_id}/images/{image_id}}

Receive a single Product Image

Parameter	Explanation
fields	Comma-separated list of fields to include in the response

GET /products/1234/images/112

HTTP/1.1 200 OK

{
  "id": 112,
  "src": "http://d26lpennugtm8s.cloudfront.net/stores/001/234/products/onyx-640-0.jpg",
  "position": 2,
  "product_id": 1234,
  "created_at": "2013-01-03T09:11:51-03:00",
  "updated_at": "2013-03-11T09:14:11-03:00"
}

Size of images

Today our API returns the URL where the image is in size 1024x1024, when changing the final part of the URL we can have the image in other sizes, namely: 50px, 100px, 240px, 320px, 480px, 640px, 1024px. Example of URLs:

• 50px = https://d3ugyf2ht6aenh.cloudfront.net/stores/239/907/products/607213-mla31157935441_062019-f-85022a547f02c6b4bf15610802532590-50-0.jpg
• 100px = https://d3ugyf2ht6aenh.cloudfront.net/stores/239/907/products/607213-mla31157935441_062019-f-85022a547f02c6b4bf15610802532590-100-0.jpg
• 240px = https://d3ugyf2ht6aenh.cloudfront.net/stores/239/907/products/607213-mla31157935441_062019-f-85022a547f02c6b4bf15610802532590-240-0.jpg
• 320px = https://d3ugyf2ht6aenh.cloudfront.net/stores/239/907/products/607213-mla31157935441_062019-f-85022a547f02c6b4bf15610802532590-320-0.jpg
• 480px = https://d3ugyf2ht6aenh.cloudfront.net/stores/239/907/products/607213-mla31157935441_062019-f-85022a547f02c6b4bf15610802532590-480-0.jpg
• 640px = https://d3ugyf2ht6aenh.cloudfront.net/stores/239/907/products/607213-mla31157935441_062019-f-85022a547f02c6b4bf15610802532590-640-0.jpg
• 1024px = https://d3ugyf2ht6aenh.cloudfront.net/stores/239/907/products/607213-mla31157935441_062019-f-85022a547f02c6b4bf15610802532590-1024-1024.jpg

If the image is uploaded in WEBP format, when changing the final part of the URL we can have only JPEG format in 1024px. Example of URL:

• 1024px = https://d3ugyf2ht6aenh.cloudfront.net/stores/239/907/products/607213-mla31157935441_062019-f-85022a547f02c6b4bf15610802532590-1024-1024.jpeg

POST /products/{product_id}/images

Create a new Product Image

Parameter	Explanation
src	The URL to the image (ex: http://example.com/charmander.jpg)
attachment	Must be image encoded in a Base64 String.
filename	A filename string (ex: mewtwo.gif)
position	A number indicating in which position of the image list, the new image should be placed
store_media_uuid	UUID of an existing Store Media image to use as the source, instead of src/attachment. Optional

Check the examples below for more details.

The optional store_media_uuid field lets you create the image directly from a previously uploaded Store Media asset, used instead of src/attachment. The media must belong to the store and be an image (image/jpeg, image/png, image/gif, image/webp, image/avif). Note: the Store Media resource used to upload media and obtain the UUID is only available on the unstable version.

POST /products/1234/images

{
  "invalid_name": "foobar"
}

HTTP/1.1 422 Unprocessable Entity

{
  "src": ["can't be blank"]
}

HTTP/1.1 422 Unprocessable Entity

{
  "code": 422,
  "message": "Unprocessable Entity",
  "description": "Product is not allowed to have more than 250 images"
}

POST /products/1234/images

{
  "src": "http://example.com/charmander.jpg"
}

HTTP/1.1 201 Created

{
  "id": 134,
  "src": "http://d26lpennugtm8s.cloudfront.net/stores/001/234/products/charmander-640-0.jpg",
  "position": 4,
  "product_id": 1234,
  "created_at": "2013-04-12T09:14:11-03:00",
  "updated_at": "2013-04-12T09:14:11-03:00"
}

POST /products/1234/images

The attachament must be the image encoded in Base64 String.

{
    "filename": "mewtwo.gif",
    "position": 5,
    "attachment": "R0lGODlhIAAgAPIAAPj4+MCgyHh4eGBgWLgomEBAQP///wAAACH/C05FVFNDQVBFMi4wAwEAAAAh
/hFwb2tlZ3VpZGUuZmlsYi5kZQAh+QQJEQAGACwAAAAAIAAgAAADj2i63P4wykmrvTjrzbv/YNgU
BUN+BUCuQFB2JNCmgeulbV2/y3rhup2pReBJgDuhgkYoUnA5mm0ZaBojyAJBadAWr8fgylXSgrEF
Mim5M1uka3H8VEm7BOmx3T59lvFVRWJcbyRNgjo+GAMCjQOHAzoDGoyOBgOYmAGTG5kOkZsil0Gc
IQMyNaUgmaqirhcJACH5BAkRAAYALAAAAAAgACAAAAOLaLrc/jDKSau9OOvNu/9gKEpFwZRfAZQs
EJhdCbhq8Hqqa9tww1a5Hc9RI/QgQd7w5CIYSTNd7XYKOI+PZIGwXGyNWKSQ9UIZtmExq6DclZ5A
KXtc4qWzPAGbPJ9TKSgFelZGY10VAyxOhW5mFgMCkQMDiwM7AxuTmAaamgGTI5aXoTM2myGdI6oa
CQA7"
}

HTTP/1.1 201 Created

{
  "id": 145,
  "src": "http://d26lpennugtm8s.cloudfront.net/stores/001/234/products/mewtwo-640-0.jpg",
  "position": 5,
  "product_id": 1234,
  "created_at": "2013-04-12T09:15:11-03:00",
  "updated_at": "2013-04-12T09:15:11-03:00"
}

POST /products/1234/images

Create the image from an existing Store Media by sending its store_media_uuid instead of src/attachment.

{
  "store_media_uuid": "41b5a07f-3a51-485c-bc76-7322e2831fd2",
  "position": 1
}

HTTP/1.1 201 Created

{
  "id": 150,
  "src": "http://d26lpennugtm8s.cloudfront.net/stores/001/234/products/charizard-1024-1024.jpg",
  "position": 1,
  "product_id": 1234,
  "created_at": "2025-06-12T09:15:11-03:00",
  "updated_at": "2025-06-12T09:15:11-03:00"
}

PUT /products/{product_id}/images/{id}

Modify an existing Product Image

You can also send an optional store_media_uuid to repoint the image to a Store Media asset, keeping the same image id. The regular src / attachment / position / alt behavior is still available. Note: the Store Media resource used to upload media and obtain the UUID is only available on the unstable version.

PUT /products/1234/images/145

{
  "id": 145,
  "src": "http://d26lpennugtm8s.cloudfront.net/stores/001/234/products/mewtwo-640-0.jpg",
  "position": 1,
  "product_id": 1234
}

HTTP/1.1 200 OK

{
  "id": 145,
  "src": "http://d26lpennugtm8s.cloudfront.net/stores/001/234/products/mewtwo-640-0.jpg",
  "position": 1,
  "product_id": 1234,
  "created_at": "2013-01-03T09:11:51-03:00",
  "updated_at": "2013-03-11T09:14:16-03:00"
}

PUT /products/1234/images/145

Repoint the image to an existing Store Media by sending its store_media_uuid.

{
  "store_media_uuid": "9b2f4c1e-1111-2222-3333-abcdef012345"
}

HTTP/1.1 200 OK

{
  "id": 145,
  "src": "http://d26lpennugtm8s.cloudfront.net/stores/001/234/products/blastoise-1024-1024.jpg",
  "position": 1,
  "product_id": 1234,
  "created_at": "2013-01-03T09:11:51-03:00",
  "updated_at": "2025-06-12T09:16:11-03:00"
}

DELETE /products/{product_id}/images/{id}

Remove a Product Image

DELETE /products/1234/images/145

HTTP/1.1 200 OK

{}