Docs
Catalog API
Images

Images

Get All Product Images

GET /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
  • 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]

  • 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.

  • data
    array[object]

  • meta
    object

    Data about the response, including pagination and collection totals.

example

Create a Product Image

POST /catalog/products/{product_id}/images

Request

Creates a Product Image.

Required Fields

  • image_file, or
  • image_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

application/json

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

  • product_id
    integer

    The unique numeric identifier for the product with which the image is associated.

  • url_zoom
    string
    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_standard
    string
    read-only

    The standard URL for this image. By default, this is used for product-page images.

  • url_thumbnail
    string
    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_tiny
    string
    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_modified
    string

    The date on which the product image was modified.

  • is_thumbnail
    boolean

    Flag for identifying whether the image is used as the productʼs thumbnail.

  • sort_order
    integer

    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
  • description
    string

    The description for the image.

  • image_url
    string

    Must be a fully qualified URL path, including protocol. Limit of 8MB per file.

  • image_file
    string

    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.

  • product_id
    integer

    The unique numeric identifier for the product with which the image is associated.

  • url_zoom
    string
    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_standard
    string
    read-only

    The standard URL for this image. By default, this is used for product-page images.

  • url_thumbnail
    string
    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_tiny
    string
    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_modified
    string

    The date on which the product image was modified.

  • is_thumbnail
    boolean

    Flag for identifying whether the image is used as the productʼs thumbnail.

  • sort_order
    integer

    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
  • description
    string

    The description for the image.

  • image_url
    string

    Must be a fully qualified URL path, including protocol. Limit of 8MB per file.

  • image_file
    string

    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.

Body

multipart/form-data

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

  • id
    integer

    The unique numeric ID of the image; increments sequentially.

  • product_id
    integer

    The unique numeric identifier for the product with which the image is associated.

  • url_zoom
    string
    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_standard
    string
    read-only

    The standard URL for this image. By default, this is used for product-page images.

  • url_thumbnail
    string
    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_tiny
    string
    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_modified
    string

    The date on which the product image was modified.

  • is_thumbnail
    boolean

    Flag for identifying whether the image is used as the productʼs thumbnail.

  • sort_order
    integer

    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
  • description
    string

    The description for the image.

  • image_url
    string

    Must be a fully qualified URL path, including protocol. Limit of 8MB per file.

  • image_file
    string

    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.

  • id
    integer

    The unique numeric ID of the image; increments sequentially.

  • product_id
    integer

    The unique numeric identifier for the product with which the image is associated.

  • url_zoom
    string
    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_standard
    string
    read-only

    The standard URL for this image. By default, this is used for product-page images.

  • url_thumbnail
    string
    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_tiny
    string
    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_modified
    string

    The date on which the product image was modified.

  • is_thumbnail
    boolean

    Flag for identifying whether the image is used as the productʼs thumbnail.

  • sort_order
    integer

    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
  • description
    string

    The description for the image.

  • image_url
    string

    Must be a fully qualified URL path, including protocol. Limit of 8MB per file.

  • image_file
    string

    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

object | application/json

Response payload for the BigCommerce API.

  • data

  • meta
    object

    Response metadata.

example

Get a Product Image

GET /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
  • 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]

  • 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.

  • data

    Common ProductImage properties.

  • meta
    object

    Response metadata.

example

Update a Product Image

PUT /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

application/json

The model for a PUT to update applicable Product Image fields.

  • product_id
    integer

    The unique numeric identifier for the product with which the image is associated.

  • url_zoom
    string
    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_standard
    string
    read-only

    The standard URL for this image. By default, this is used for product-page images.

  • url_thumbnail
    string
    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_tiny
    string
    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.

  • image_file
    string

    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_thumbnail
    boolean

    Flag for identifying whether the image is used as the productʼs thumbnail.

  • sort_order
    integer

    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
  • description
    string

    The description for the image.

  • image_url
    string

    Must be a fully qualified URL path, including protocol. Limit of 8MB per file.

  • product_id
    integer

    The unique numeric identifier for the product with which the image is associated.

  • url_zoom
    string
    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_standard
    string
    read-only

    The standard URL for this image. By default, this is used for product-page images.

  • url_thumbnail
    string
    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_tiny
    string
    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.

  • image_file
    string

    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_thumbnail
    boolean

    Flag for identifying whether the image is used as the productʼs thumbnail.

  • sort_order
    integer

    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
  • description
    string

    The description for the image.

  • image_url
    string

    Must be a fully qualified URL path, including protocol. Limit of 8MB per file.

example

Response

Body

object | application/json

Response payload for the BigCommerce API.

  • data

  • meta
    object

    Response metadata.

example

Delete a Product Image

DELETE /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.

example

Response

Did you find what you were looking for?