BigCommerce
Catalog API
Images

Catalog - Products

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

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

    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

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

  • url_thumbnail
    string

    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

    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.

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

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

    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

      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

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

    • url_thumbnail
      string

      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

      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.

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

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