Skip to main content

The REST Admin API is a legacy API as of October 1, 2024. Starting April 1, 2025, all new public apps must be built exclusively with the GraphQL Admin API. For details and migration steps, visit our migration guide.

Product Image

Requires products access scope.
Important

Listing, creating, updating, and deleting product images is deprecated as of REST API 2025-01. For more information, refer to the guide to the new product model.

Products are easier to sell if customers can see pictures of them, which is why there are product images.

Any product may have up to 250 images, and images can be in .png, .gif or .jpg format.

Best practices for naming image files

To successfully upload or update images, follow these best practices when naming your image files:

  • Don't use spaces in the file name. Example: my file name.png
  • Don't begin your file name with symbols, like "!". Example: !my_file_name.png
  • Avoid using periods before the file extension. Example: my_file_name..png
  • Avoid long, complicated file names that contain excess characters.

    Example: my_---_file_---_name_---.png

Was this section helpful?
#

Endpoints

Anchor to

The Product Image resource

Anchor to

Properties

created_at
->
createdAt

The date and time when the product image was created. The API returns this value in ISO 8601 format.

id
integer
int64
->
id

A unique numeric identifier for the product image.

position

The order of the product image in the list. The first product image is at position 1 and is the "main" image for the product.

product_id
deprecated

The id of the product associated with the image.

variant_ids
deprecated

An array of variant ids associated with the image.

src
->
url

Specifies the location of the product image. This parameter supports Liquid filters that you can use to retrieve modified copies of the image.

width
->
width

Width dimension of the image which is determined on upload.

height
->
height

Height dimension of the image which is determined on upload.

updated_at
->
updatedAt

The date and time when the product image was last modified. The API returns this value in ISO 8601 format.

Was this section helpful?
{}

The Product Image resource

{
"created_at": "2012-03-13T16:09:58-04:00",
"id": 850703190,
"position": 1,
"product_id": 632910392,
"variant_ids": [
808950810
],
"src": "http://static.shopify.com/products/ipod-nano.png",
"width": 640,
"height": 480,
"updated_at": "2012-03-13T16:09:58-04:00"
}

Anchor to POST request, Create a new Product Image
post
Create a new Product Image

productCreateMedia

Create a new product image

Anchor to Parameters of Create a new Product ImageParameters

api_version
string
required
product_id
string
required
Was this section helpful?

Anchor to post-products-product-id-images-examplesExamples

Create a new product image with a metafield

Path parameters
product_id=632910392
string
required

Create a new product image and attach it to product variants

Path parameters
product_id=632910392
string
required

Create a new product image and make it the main image

Path parameters
product_id=632910392
string
required

Create a new product image using a source URL that will be downloaded by Shopify

Path parameters
product_id=632910392
string
required

Create a new product image with included image data as attachment

Path parameters
product_id=632910392
string
required
Was this section helpful?
post

/admin/api/unstable/products/632910392/images.json

curl -d '{"image":{"position":1,"metafields":[{"key":"new","value":"newvalue","type":"single_line_text_field","namespace":"global"}],"attachment":"R0lGODlhbgCMAPf/APbr48VySrxTO7IgKt2qmKQdJeK8lsFjROG5p/nz7Zg3\nMNmnd7Q1MLNVS9GId71hSJMZIuzTu4UtKbeEeakhKMl8U8WYjfr18YQaIbAf\nKKwhKdKzqpQtLebFortOOejKrOjZ1Mt7aMNpVbAqLLV7bsNqR+3WwMqEWenN\nsZYxL/Ddy/Pm2e7ZxLlUQrIjNPXp3bU5MbhENbEtLtqhj5ZQTfHh0bMxL7Ip\nNsNyUYkZIrZJPcqGdYIUHb5aPKkeJnoUHd2yiJkiLKYiKLRFOsyJXKVDO8up\nosFaS+TBnK4kKti5sNaYg/z49aqYl5kqLrljUtORfMOlo/36+H4ZH8yDYq0f\nKKFYTaU9MrY8MrZBNXwXHpgaIdGVYu/byLZNP9SaZLIyOuXCtHkpJst+Wpcm\nLMyCa8BfP9GMb9KQdPDd1PPk1sd5VP79/L5dQZ0bI9+ymqssK9WcfIoXHdzG\nxdWWfteib79lSr1YP86MYurQxKdcUKdMQr5ZSfPs6YEZH8uhl4oWIenMuurQ\nttmejaqoqsqBVaAcJLlJN5kvMLlZRMNsSL5fRak0LbdQQMVvSPjw6cJnRpkf\nKtmjhvfu5cJtT7IuOMVvWLY/M/37+o0YH9ibhtSYdObErc6HarM9NnYSGNGR\navLi09unje3WyeO8rsVrT7tdRtK3uffu6NWeaL9pTJIjJrM4NPbx8cdyX7M7\nPYYVHu7j4KgoNJAYIKtkV5o9MsOcldicis+RYNutfrhFOZ0hJbqinZ8bI8h5\nUObFuOfItJsfJrJfUOfIqc+PXqQtK8RnSbA4Mcd3Tm0SGbpXQ8aqp7RLNs+s\novHfzpVhV9iggMd1TLtbRKUdKXEQFsd4XrZRPLIgMZUeJ+jKvrAlK6AhJ65A\nMpMpKuC3j5obIsRwS7hAN8l/YtvDvnYXHbAoLI47SIUsOMenorF4gO/m4+fH\npo4vLZ8oKMukqp0cJbhVSMV2UuPR0bAfMLIrLrg/OcJwT8h+Vt+wn8eurLlh\nQrIfKHQOHHQOHf///////yH5BAEAAP8ALAAAAABuAIwAAAj/AP8JHDhQXjpz\n/PopXNiPn0OHDRMmbKhQIsOJFS1SxAhxI8SHFzVeDBnx48iNBAeeOkcxokeX\nFRdOnAlSokaaLXNujJkxo8iYHRkKtWkzZSsaOXkAWsoUECynsHgoqEW1qtVa\nU7Mq2Mq1K9cUW8GKTUG2rNkUHNByWMuWLdWva7t1W7UKG4S7eO/ycEhQHgaK\nsL4VGGyocGE3br5929KuxQFFkEtIlgypsuUDmDMfWGRmUZvPoEHfGU36jgDT\nLQSoVt3IQ2sPsL0IUNZGlZ0H0lo00jEkCytWMspdGzBgn/F9EBIWnKIQlqHB\nhA0bQpx48Z7UAkoEcMTdUeTJJSxf/4akOTNnzqHb3GkjrUdp0gKwq77jWdod\nO7dNKWvhRUcWT6zYQI82xB03AAQNCdTKX/xAAB10hfVCnRtbVIhIAy14oJoZ\nAXS4XXfdQaYIeOGJRx555Z1nRnrqqUeaMtIYY8dmn7Vg2yK57TYEgAzIQGBx\nxyXHj0A0OOTggxFKSN1iWwTTAIYanpYdMtFE4+GVIHrn3XeUmVhZeWiIMoOY\nnVQDGiTgKALJjIssIsADt0mjjI6+AXcDgQYi2M8/7ijEwzRIFmBIL9NVV+EW\nVzyZ4Wqj9RBABchQWeWkV3aY5ZYjjgieeKL446mnjxwAiZVpliAjZqblt19/\n/7HCwIAFGv+X3J4s9fMckoYhphiTQTwJ5Wqn9dDDAWuMUUEFviTrS6STVlmp\npVmKqCkOn34aB6TIBAAOJeHZAYl6ptixSCL8edGbq8HFeqBDcygEyIOCGqYk\nkxUW
-X POST "https://your-development-store.myshopify.com/admin/api/unstable/products/632910392/images.json" \
-H "X-Shopify-Access-Token: {access_token}" \
-H "Content-Type: application/json"

{}

Response

JSON
HTTP/1.1 200 OK
{
"image": {
"id": 1001473982,
"alt": null,
"position": 1,
"product_id": 632910392,
"created_at": "2025-04-07T13:03:44-04:00",
"updated_at": "2025-04-07T13:03:44-04:00",
"admin_graphql_api_id": "gid://shopify/MediaImage/1072273692",
"width": 110,
"height": 140,
"src": "https://cdn.shopify.com/s/files/1/0005/4838/0009/files/rails_logo.gif?v=1744045424",
"variant_ids": []
}
}

Anchor to GET request, Receive a list of all Product Images
get
Receive a list of all Product Images

product

Get all product images

Anchor to Parameters of Receive a list of all Product ImagesParameters

api_version
string
required
product_id
string
required
fields

comma-separated list of fields to include in the response

since_id

Restrict results to after the specified ID

Was this section helpful?

Anchor to get-products-product-id-images-examplesExamples

Get all product images for a product

Path parameters
product_id=632910392
string
required

Get all product images for a product after a specified ID

Path parameters
product_id=632910392
string
required
Query parameters
since_id=850703190

Restrict results to after the specified ID

Was this section helpful?
get

/admin/api/unstable/products/632910392/images.json

curl -X GET "https://your-development-store.myshopify.com/admin/api/unstable/products/632910392/images.json" \
-H "X-Shopify-Access-Token: {access_token}"

{}

Response

JSON
HTTP/1.1 200 OK
{
"images": [
{
"id": 562641783,
"alt": null,
"position": 2,
"product_id": 632910392,
"created_at": "2025-04-03T16:15:58-04:00",
"updated_at": "2025-04-03T16:15:58-04:00",
"admin_graphql_api_id": "gid://shopify/MediaImage/1071517486",
"width": 123,
"height": 456,
"src": "https://cdn.shopify.com/s/files/1/0005/4838/0009/products/ipod-nano-2.png?v=1743711358",
"variant_ids": [
808950810
]
},
{
"id": 850703190,
"alt": null,
"position": 1,
"product_id": 632910392,
"created_at": "2025-04-03T16:15:58-04:00",
"updated_at": "2025-04-03T16:15:58-04:00",
"admin_graphql_api_id": "gid://shopify/MediaImage/498048120",
"width": 123,
"height": 456,
"src": "https://cdn.shopify.com/s/files/1/0005/4838/0009/products/ipod-nano.png?v=1743711358",
"variant_ids": []
},
{
"id": 378407906,
"alt": null,
"position": 3,
"product_id": 632910392,
"created_at": "2025-04-03T16:15:58-04:00",
"updated_at": "2025-04-03T16:15:58-04:00",
"admin_graphql_api_id": "gid://shopify/MediaImage/220090436",
"width": 123,
"height": 456,
"src": "https://cdn.shopify.com/s/files/1/0005/4838/0009/products/ipod-nano.png?v=1743711358",
"variant_ids": []
}
]
}

Anchor to GET request, Receive a single Product Image
get
Receive a single Product Image

node

Get a single product image by id

Anchor to Parameters of Receive a single Product ImageParameters

api_version
string
required
image_id
string
required
product_id
string
required
fields

comma-separated list of fields to include in the response

Was this section helpful?

Anchor to get-products-product-id-images-image-id-examplesExamples

Show product image

Was this section helpful?
get

/admin/api/unstable/products/632910392/images/850703190.json

curl -X GET "https://your-development-store.myshopify.com/admin/api/unstable/products/632910392/images/850703190.json" \
-H "X-Shopify-Access-Token: {access_token}"

{}

Response

JSON
HTTP/1.1 200 OK
{
"image": {
"id": 850703190,
"alt": null,
"position": 1,
"product_id": 632910392,
"created_at": "2025-04-03T16:15:58-04:00",
"updated_at": "2025-04-03T16:15:58-04:00",
"admin_graphql_api_id": "gid://shopify/MediaImage/498048120",
"width": 123,
"height": 456,
"src": "https://cdn.shopify.com/s/files/1/0005/4838/0009/products/ipod-nano.png?v=1743711358",
"variant_ids": []
}
}

Anchor to GET request, Receive a count of all Product Images
get
Receive a count of all Product Images

product

Get a count of all product images

Anchor to Parameters of Receive a count of all Product ImagesParameters

api_version
string
required
product_id
string
required
since_id

Restrict results to after the specified ID

Was this section helpful?

Anchor to get-products-product-id-images-count-examplesExamples

Get a count all product images

Path parameters
product_id=632910392
string
required

Get a count of all product images after a specified ID

Path parameters
product_id=632910392
string
required
Query parameters
since_id=850703190

Restrict results to after the specified ID

Was this section helpful?
get

/admin/api/unstable/products/632910392/images/count.json

curl -X GET "https://your-development-store.myshopify.com/admin/api/unstable/products/632910392/images/count.json" \
-H "X-Shopify-Access-Token: {access_token}"

{}

Response

JSON
HTTP/1.1 200 OK
{
"count": 3
}

Anchor to PUT request, Modify an existing Product Image
put
Modify an existing Product Image

productUpdateMedia

Modify an existing product image

Anchor to Parameters of Modify an existing Product ImageParameters

api_version
string
required
image_id
string
required
product_id
string
required
Was this section helpful?

Anchor to put-products-product-id-images-image-id-examplesExamples

Modify an image and change its position and alt tag content

Modify an image; add a metafield

Modify an image; add it to product variants

Was this section helpful?
put

/admin/api/unstable/products/632910392/images/850703190.json

curl -d '{"image":{"id":850703190,"position":2,"alt":"new alt tag content"}}' \
-X PUT "https://your-development-store.myshopify.com/admin/api/unstable/products/632910392/images/850703190.json" \
-H "X-Shopify-Access-Token: {access_token}" \
-H "Content-Type: application/json"

{}

Response

JSON
HTTP/1.1 200 OK
{
"image": {
"id": 850703190,
"alt": "new alt tag content",
"position": 1,
"product_id": 632910392,
"created_at": "2025-04-03T16:15:58-04:00",
"updated_at": "2025-04-07T13:04:07-04:00",
"admin_graphql_api_id": "gid://shopify/MediaImage/498048120",
"width": 123,
"height": 456,
"src": "https://cdn.shopify.com/s/files/1/0005/4838/0009/products/ipod-nano.png?v=1743711358",
"variant_ids": []
}
}

Anchor to DELETE request, Remove an existing Product Image
del
Remove an existing Product Image

productDeleteMedia

Anchor to Parameters of Remove an existing Product ImageParameters

api_version
string
required
image_id
string
required
product_id
string
required
Was this section helpful?

Anchor to delete-products-product-id-images-image-id-examplesExamples

Delete a product image

Was this section helpful?
del

/admin/api/unstable/products/632910392/images/850703190.json

curl -X DELETE "https://your-development-store.myshopify.com/admin/api/unstable/products/632910392/images/850703190.json" \
-H "X-Shopify-Access-Token: {access_token}"

{}

Response

JSON
HTTP/1.1 200 OK
{}