Images

Get All Product Images

GET https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/products/{product_id}/images

Request

Returns a list of Product Images. Optional parameters can be passed in.

Authentication

X-Auth-Token in header

Parameters

store_hash in path - string
Accept in header with default of application/json - string
required
The MIME type of the response body.
product_id in path - integer
required
The ID of the Product to which the resource belongs.
page in query - integer
Specifies the page number in a limited (paginated) list of products.
limit in query with default of 50 - integer
Controls the number of items per page in a limited (paginated) list of products.
include_fields in query - array
Fields to include, in a comma-separated list. The ID and the specified fields will be returned.
Type: array[string]
Allowed: name | type | sku | description | weight | width | depth | height | price | cost_price | retail_price | sale_price | map_price | tax_class_id | product_tax_code | calculated_price | categories | brand_id | option_set_id | option_set_display | inventory_level | inventory_warning_level | inventory_tracking | reviews_rating_sum | reviews_count | total_sold | fixed_cost_shipping_price | is_free_shipping | is_visible | is_featured | related_products | warranty | bin_picking_number | layout_file | upc | mpn | gtin | date_last_imported | search_keywords | availability | availability_description | condition | is_condition_shown | order_quantity_minimum | order_quantity_maximum | page_title | meta_keywords | meta_description | date_created | date_modified | view_count | preorder_release_date | preorder_message | is_preorder_only | is_price_hidden | price_hidden_label | custom_url | base_variant_id | open_graph_type | open_graph_title | open_graph_description | open_graph_use_meta_description | open_graph_use_product_name | open_graph_use_image
exclude_fields in query - array
Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.
Type: array[string]

example

Response

Body

object | application/json

Response payload for the BigCommerce API.

dataarray[object]
metaobject
Data about the response, including pagination and collection totals.

example

Create a Product Image

POST https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/products/{product_id}/images

Request

Creates a Product Image.

Required Fields

image_file, or
image_url

Usage Notes

image_url
- 255 character limit
Content-Type
- For image_file, use the multipart/form-data media type. For image_url, use the application/json type. See Adding product images for more information.
You can create only one image at a time. A product can have up to 1000 images.
Supported image file types are BMP, GIF, JPEG, PNG, WBMP, XBM, and WEBP.
Each image file or image uploaded by URL can be up to 8 MB.

Authentication

X-Auth-Token in header

Parameters

store_hash in path - string
Accept in header with default of application/json - string
required
The MIME type of the response body.
product_id in path - integer
required
The ID of the Product to which the resource belongs.

Body

object | application/json

The model for a POST to create an image on a product.

product_idinteger
The unique numeric identifier for the product with which the image is associated.
image_urlstring
The URL for an image displayed on the storefront when the conditions are applied. Limit of 8MB per file.
Cannot be used with image_file.
<= 255 characters
is_thumbnailboolean
Flag for identifying whether the image is used as the productʼs thumbnail.
sort_orderinteger
The order in which the image will be displayed on the product page. Higher integers give the image a lower priority. When updating, if the image is given a lower priority, all images with a sort_order the same as or greater than the imageʼs new sort_order value will have their sort_orders reordered.
Min: -2147483648
Max: 2147483647
descriptionstring
The description for the image.
date_modifiedstring
The date on which the product image was modified.

Body

object | multipart/form-data

The model for a POST to create an image on a product.

product_idinteger
The unique numeric identifier for the product with which the image is associated.
date_modifiedstring
The date on which the product image was modified.
is_thumbnailboolean
Flag for identifying whether the image is used as the productʼs thumbnail.
sort_orderinteger
The order in which the image will be displayed on the product page. Higher integers give the image a lower priority. When updating, if the image is given a lower priority, all images with a sort_order the same as or greater than the imageʼs new sort_order value will have their sort_orders reordered.
Min: -2147483648
Max: 2147483647
descriptionstring
The description for the image.
image_filestring
The local path to the original image file uploaded to BigCommerce. Use image_url when creating a product.
Must be sent as a multipart/form-data field in the request body. Limit of 8 MB per file. Cannot be used with image_url.

example

Response

Success

Body

object | application/json

Response payload for the BigCommerce API.

data
One of:
idinteger
The unique numeric ID of the image; increments sequentially.
product_idinteger
The unique numeric identifier for the product with which the image is associated.
url_zoomstring
read-only
The zoom URL for this image. By default, this is used as the zoom image on product pages when zoom images are enabled. You should provide an image smaller than 1280x1280; otherwise, the API returns a resized image.
url_standardstring
read-only
The standard URL for this image. By default, this is used for product-page images.
url_thumbnailstring
read-only
The thumbnail URL for this image. By default, this is the image size used on the category page and in side panels.
url_tinystring
read-only
The tiny URL for this image. By default, this is the image size used for thumbnails beneath the product image on a product page.
date_modifiedstring
The date on which the product image was modified.
is_thumbnailboolean
Flag for identifying whether the image is used as the productʼs thumbnail.
sort_orderinteger
The order in which the image will be displayed on the product page. Higher integers give the image a lower priority. When updating, if the image is given a lower priority, all images with a sort_order the same as or greater than the imageʼs new sort_order value will have their sort_orders reordered.
Min: -2147483648
Max: 2147483647
descriptionstring
The description for the image.
image_urlstring
Must be a fully qualified URL path, including protocol. Limit of 8MB per file.
metaobject
Response metadata.

example

Unprocessable Entity.

May occur if the Content-Type header is set to multipart/form-data rather than application/json when creating a product image using image_url.

Body

object | application/json

statusnumber
required
titlestring
required
>= 1 characters
typestring
required
>= 1 characters

example

Get a Product Image

GET https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/products/{product_id}/images/{image_id}

Request

Returns a single Product Image. Optional parameters can be passed in.

Authentication

X-Auth-Token in header

Parameters

store_hash in path - string
Accept in header with default of application/json - string
required
The MIME type of the response body.
product_id in path - integer
required
The ID of the Product to which the resource belongs.
image_id in path - integer
required
The ID of the Image that is being operated on.
include_fields in query - array
Fields to include, in a comma-separated list. The ID and the specified fields will be returned.
Type: array[string]
Allowed: name | type | sku | description | weight | width | depth | height | price | cost_price | retail_price | sale_price | map_price | tax_class_id | product_tax_code | calculated_price | categories | brand_id | option_set_id | option_set_display | inventory_level | inventory_warning_level | inventory_tracking | reviews_rating_sum | reviews_count | total_sold | fixed_cost_shipping_price | is_free_shipping | is_visible | is_featured | related_products | warranty | bin_picking_number | layout_file | upc | mpn | gtin | date_last_imported | search_keywords | availability | availability_description | condition | is_condition_shown | order_quantity_minimum | order_quantity_maximum | page_title | meta_keywords | meta_description | date_created | date_modified | view_count | preorder_release_date | preorder_message | is_preorder_only | is_price_hidden | price_hidden_label | custom_url | base_variant_id | open_graph_type | open_graph_title | open_graph_description | open_graph_use_meta_description | open_graph_use_product_name | open_graph_use_image
exclude_fields in query - array
Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.
Type: array[string]

example

Response

Body

object | application/json

Response payload for the BigCommerce API.

dataobject
Common ProductImage properties.
metaobject
Response metadata.

example

Update a Product Image

PUT https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/products/{product_id}/images/{image_id}

Request

Updates a Product Image.

Usage Notes

image_url
- 255 character limit
Each image file or image uploaded by URL can be up to 8 MB.
For file uploads, send a POST request using the multipart/form-data media type

Authentication

X-Auth-Token in header

Parameters

store_hash in path - string
Accept in header with default of application/json - string
required
The MIME type of the response body.
product_id in path - integer
required
The ID of the Product to which the resource belongs.
image_id in path - integer
required
The ID of the Image that is being operated on.
Content-Type in header with default of application/json - string
required
The MIME type of the request body.

Body

object | application/json

The model for a POST or PUT to create or update an image on a product.

product_idinteger
The unique numeric identifier for the product with which the image is associated.
image_urlstring
The URL for an image displayed on the storefront when the conditions are applied. Limit of 8MB per file.
Cannot be used with image_file.
<= 255 characters
is_thumbnailboolean
Flag for identifying whether the image is used as the productʼs thumbnail.
sort_orderinteger
The order in which the image will be displayed on the product page. Higher integers give the image a lower priority. When updating, if the image is given a lower priority, all images with a sort_order the same as or greater than the imageʼs new sort_order value will have their sort_orders reordered.
Min: -2147483648
Max: 2147483647
descriptionstring
The description for the image.
date_modifiedstring
The date on which the product image was modified.

Body

object | multipart/form-data

The model for a POST or PUT to create or update an image on a product.

product_idinteger
The unique numeric identifier for the product with which the image is associated.
date_modifiedstring
The date on which the product image was modified.
is_thumbnailboolean
Flag for identifying whether the image is used as the productʼs thumbnail.
sort_orderinteger
The order in which the image will be displayed on the product page. Higher integers give the image a lower priority. When updating, if the image is given a lower priority, all images with a sort_order the same as or greater than the imageʼs new sort_order value will have their sort_orders reordered.
Min: -2147483648
Max: 2147483647
descriptionstring
The description for the image.
image_filestring
The local path to the original image file uploaded to BigCommerce. Use image_url when creating a product.
Must be sent as a multipart/form-data field in the request body. Limit of 8 MB per file. Cannot be used with image_url.

example

Response

Success

Body

object | application/json

Response payload for the BigCommerce API.

data
One of:
idinteger
The unique numeric ID of the image; increments sequentially.
product_idinteger
The unique numeric identifier for the product with which the image is associated.
url_zoomstring
read-only
The zoom URL for this image. By default, this is used as the zoom image on product pages when zoom images are enabled. You should provide an image smaller than 1280x1280; otherwise, the API returns a resized image.
url_standardstring
read-only
The standard URL for this image. By default, this is used for product-page images.
url_thumbnailstring
read-only
The thumbnail URL for this image. By default, this is the image size used on the category page and in side panels.
url_tinystring
read-only
The tiny URL for this image. By default, this is the image size used for thumbnails beneath the product image on a product page.
date_modifiedstring
The date on which the product image was modified.
is_thumbnailboolean
Flag for identifying whether the image is used as the productʼs thumbnail.
sort_orderinteger
The order in which the image will be displayed on the product page. Higher integers give the image a lower priority. When updating, if the image is given a lower priority, all images with a sort_order the same as or greater than the imageʼs new sort_order value will have their sort_orders reordered.
Min: -2147483648
Max: 2147483647
descriptionstring
The description for the image.
image_urlstring
Must be a fully qualified URL path, including protocol. Limit of 8MB per file.
metaobject
Response metadata.

example

Delete a Product Image

DELETE https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/products/{product_id}/images/{image_id}

Request

Deletes a Product Image.

Authentication

X-Auth-Token in header

Parameters

store_hash in path - string
Accept in header with default of application/json - string
required
The MIME type of the response body.
product_id in path - integer
required
The ID of the Product to which the resource belongs.
image_id in path - integer
required
The ID of the Image that is being operated on.

example

Response

Did you find what you were looking for?

Images

Get All Product Images

Request

Authentication

Parameters

example

Response

Body

dataarray[object]

metaobject

example

Body

statusinteger

titlestring

typestring

instancestring

example

Create a Product Image

Request

Authentication

Parameters

Body

product_idinteger

image_urlstring

is_thumbnailboolean

sort_orderinteger

descriptionstring

date_modifiedstring

Body

product_idinteger

date_modifiedstring

is_thumbnailboolean

sort_orderinteger

descriptionstring

image_filestring

example

Response

Body

data

idinteger

product_idinteger

url_zoomstringread-only

url_standardstringread-only

url_thumbnailstringread-only

url_tinystringread-only

date_modifiedstring

is_thumbnailboolean

sort_orderinteger

descriptionstring

image_urlstring

metaobject

example

Body

example

Body

statusinteger

titlestring

typestring

instancestring

example

Body

statusnumberrequired

titlestringrequired

typestringrequired

example

Get a Product Image

Request

Authentication

Parameters

example

Response

Body

dataobject

metaobject

example

Body

statusinteger

titlestring

typestring

instancestring

url_zoomstring
read-only

url_standardstring
read-only

url_thumbnailstring
read-only

url_tinystring
read-only

statusnumber
required

titlestring
required

typestring
required

url_zoomstring
read-only

url_standardstring
read-only

url_thumbnailstring
read-only

url_tinystring
read-only