Catalog - Products
Get All Product Images
GET /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 - required
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 - integer
Controls the number of items per page in a limited (paginated) list of products.
- include_fields in query - string
Fields to include, in a comma-separated list. The ID and the specified fields will be returned.
- exclude_fields in query - string
Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.
example
Response
Body
Response payload for the BigCommerce API.
dataarray[object]
metaobject
Data about the response, including pagination and collection totals.
example
Create a Product Image
POST /stores/{store_hash}/v3/catalog/products/{product_id}/images
Request
Creates a Product Image.
Required Fields
image_file
, orimage_url
Usage Notes
image_url
-255
character limit- For file uploads, use the
multipart/form-data
media type. - 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 - required
Parameters
- store_hash in path - string
- Content-Type in header with default of application/json - string - required
The MIME type of the request body.
Body
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.
url_zoomstring
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
The standard URL for this image. By default, this is used for product-page images.
url_thumbnailstring
The thumbnail URL for this image. By default, this is the image size used on the category page and in side panels.
url_tinystring
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 newsort_order
value will have theirsort_order
s reordered.descriptionstring
The description for the image.
image_urlstring
Must be a fully qualified URL path, including protocol. Limit of 8MB per file.
image_filestring
The local path to the original image file uploaded to BigCommerce. A
multipart/form-data
media type.Must be sent as a
multipart/form-data
field in the request body. Limit of 8 MB per file.
example
Response
Success
Body
Response payload for the BigCommerce API.
dataobject
metaobject
Response metadata.
example
Get a Product Image
GET /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 - required
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 - string
Fields to include, in a comma-separated list. The ID and the specified fields will be returned.
- exclude_fields in query - string
Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.
example
Response
Body
Response payload for the BigCommerce API.
data
Common ProductImage properties.
metaobject
Response metadata.
example
Update a Product Image
PUT /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 - required
Parameters
- store_hash in path - string
- Content-Type in header with default of application/json - string - required
The MIME type of the request body.
Body
The model for a PUT to update applicable Product Image fields.
product_idinteger
The unique numeric identifier for the product with which the image is associated.
url_zoomstring
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
The standard URL for this image. By default, this is used for product-page images.
url_thumbnailstring
The thumbnail URL for this image. By default, this is the image size used on the category page and in side panels.
url_tinystring
The tiny URL for this image. By default, this is the image size used for thumbnails beneath the product image on a product page.
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.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 newsort_order
value will have theirsort_order
s reordered.descriptionstring
The description for the image.
image_urlstring
Must be a fully qualified URL path, including protocol. Limit of 8MB per file.
example
Response
Body
Response payload for the BigCommerce API.
dataobject
metaobject
Response metadata.
example
Delete a Product Image
DELETE /stores/{store_hash}/v3/catalog/products/{product_id}/images/{image_id}
Request
Deletes a Product Image.
Authentication
- X-Auth-Token in header - required
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.