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
| 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 |
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 |
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"
}
]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"
}
]Receive a single Product Image
| Parameter | Explanation |
|---|---|
| fields | Comma-separated list of fields to include in the response |
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"
}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
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 |
Check the examples below for more details.
{
"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"
}{
"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"
}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"
}Modify an existing Product Image
{
"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"
}Remove a Product Image
HTTP/1.1 200 OK
{}