Skip to main content

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​

PropertyExplanation
idThe unique numeric identifier for the Product Image
product_idThe id of the product associated with the image
srcURL of the product image
positionNumber indicating the position of the image in the product's image list. 1 is the first and the main product image
created_atDate when the Product Image was created in ISO 8601 format
updated_atDate when the Product Image was last updated in ISO 8601 format
altImage alt text helps search engines like Google understand when to show the image in a search result

Endpoints​

GET /products/{product_id}/images​

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

ParameterExplanation
since_idRestrict results to after the specified ID
srcShow Product Images with a given URL
positionShow Product Images at a given position
pagePage to show
per_pageAmount of results
fieldsComma-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

ParameterExplanation
fieldsComma-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:

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:

POST /products/{product_id}/images​

Create a new Product Image

ParameterExplanation
srcThe URL to the image (ex: http://example.com/charmander.jpg)
attachmentMust be image encoded in a Base64 String.
filenameA filename string (ex: mewtwo.gif)
positionA number indicating in which position of the image list, the new image should be placed

Check the examples below for more details.

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"
}

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

Modify an existing Product Image

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"
}

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

Remove a Product Image

DELETE /products/1234/images/145​

HTTP/1.1 200 OK

{}