Thanks for being patient while we implement your feedback to improve the developer experience.

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

curl --request GET \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/catalog/products/[product_id]/images' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

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

{
  "data": [
    {
      "id": 382,
      "product_id": 158,
      "is_thumbnail": true,
      "sort_order": 0,
      "description": "",
      "image_file": "a/521/foglinenbeigestripetowel1b_1024x1024__83011__60806.jpg",
      "url_zoom": "https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/382/foglinenbeigestripetowel1b_1024x1024__83011__60806.1534344511.1280.1280.jpg?c=2",
      "url_standard": "https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/382/foglinenbeigestripetowel1b_1024x1024__83011__60806.1534344511.560.850.jpg?c=2",
      "url_thumbnail": "https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/382/foglinenbeigestripetowel1b_1024x1024__83011__60806.1534344511.330.500.jpg?c=2",
      "url_tiny": "https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/382/foglinenbeigestripetowel1b_1024x1024__83011__60806.1534344511.66.100.jpg?c=2",
      "date_modified": "2018-08-15T14:48:31+00:00"
    },
    {
      "id": 383,
      "product_id": 158,
      "is_thumbnail": false,
      "sort_order": 0,
      "description": "",
      "image_file": "k/050/foglinenbeigestripetowel2b_1024x1024__16082__46564.jpg",
      "url_zoom": "https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/383/foglinenbeigestripetowel2b_1024x1024__16082__46564.1534344511.1280.1280.jpg?c=2",
      "url_standard": "https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/383/foglinenbeigestripetowel2b_1024x1024__16082__46564.1534344511.560.850.jpg?c=2",
      "url_thumbnail": "https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/383/foglinenbeigestripetowel2b_1024x1024__16082__46564.1534344511.330.500.jpg?c=2",
      "url_tiny": "https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/383/foglinenbeigestripetowel2b_1024x1024__16082__46564.1534344511.66.100.jpg?c=2",
      "date_modified": "2018-08-15T14:48:31+00:00"
    }
  ],
  "meta": {
    "pagination": {
      "total": 2,
      "count": 2,
      "per_page": 50,
      "current_page": 1,
      "total_pages": 1,
      "links": {
        "current": "?page=1&limit=50"
      }
    }
  }
}

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
  • Only one image at a time can be created
  • Supported image file types are BMP, GIF, JPEG, PNG, WBMP, XBM, and WEBP.

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.

  • image_file    string

    The local path to the original image file uploaded to BigCommerce. A multipart/form-data media type.

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

  • 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

    Must be sent as a multipart/form-data field in the request body. Limit of 1MB per file.

    example

    {
  "product_id": 0,
  "image_file": "string",
  "date_modified": "2019-08-24T14:15:22Z",
  "is_thumbnail": true,
  "sort_order": -2147483648,
  "description": "string",
  "image_url": "string"
}

    Response

    Success

    Body

    object | application/json

    Response payload for the BigCommerce API.

    • data      object

    • meta      object

      Response metadata.

    example

    {
  "data": {
    "id": 485,
    "product_id": 158,
    "is_thumbnail": false,
    "sort_order": 1,
    "description": "",
    "image_file": "o/381/product-image__98178.png",
    "url_zoom": "https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/485/product-image__98178.1536854227.1280.1280.png?c=2",
    "url_standard": "https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/485/product-image__98178.1536854227.560.850.png?c=2",
    "url_thumbnail": "https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/485/product-image__98178.1536854227.330.500.png?c=2",
    "url_tiny": "https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/485/product-image__98178.1536854227.66.100.png?c=2",
    "date_modified": "2018-09-13T15:57:07+00:00"
  },
  "meta": {}
}

    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.

    • 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

    curl --request GET \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/catalog/products/[product_id]/images/[image_id]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

    Response

    Body

    object | application/json

    Response payload for the BigCommerce API.

    • data

      Common ProductImage properties.

    • meta      object

      Response metadata.

    example

    {
  "data": {
    "id": 485,
    "product_id": 158,
    "is_thumbnail": false,
    "sort_order": 1,
    "description": "",
    "image_file": "o/381/product-image__98178.png",
    "url_zoom": "https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/485/product-image__98178.1536854227.1280.1280.png?c=2",
    "url_standard": "https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/485/product-image__98178.1536854227.560.850.png?c=2",
    "url_thumbnail": "https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/485/product-image__98178.1536854227.330.500.png?c=2",
    "url_tiny": "https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/485/product-image__98178.1536854227.66.100.png?c=2",
    "date_modified": "2018-09-13T15:57:07+00:00"
  },
  "meta": {}
}

    Update a Product Image

    PUT /catalog/products/{product_id}/images/{image_id}

    Request

    Updates a Product Image.

    Usage Notes

    • image_url - 255 character limit
    • 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.

    • image_id in path - integer - required

      The ID of the Image that is being operated on.

    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.

    • 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. Limit of 1MB 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

      {
  "product_id": 0,
  "image_file": "string",
  "is_thumbnail": true,
  "sort_order": -2147483648,
  "description": "string",
  "image_url": "string"
}

      Response

      Body

      object | application/json

      Response payload for the BigCommerce API.

      • data        object

      • meta        object

        Response metadata.

      example

      {
  "data": {
    "id": 485,
    "product_id": 158,
    "is_thumbnail": false,
    "sort_order": 1,
    "description": "",
    "image_file": "o/381/product-image__98178.png",
    "url_zoom": "https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/485/product-image__98178.1536854227.1280.1280.png?c=2",
    "url_standard": "https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/485/product-image__98178.1536854227.560.850.png?c=2",
    "url_thumbnail": "https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/485/product-image__98178.1536854227.330.500.png?c=2",
    "url_tiny": "https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/485/product-image__98178.1536854227.66.100.png?c=2",
    "date_modified": "2018-09-13T15:57:07+00:00"
  },
  "meta": {}
}

      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.

      • image_id in path - integer - required

        The ID of the Image that is being operated on.

      example

      curl --request DELETE \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/catalog/products/[product_id]/images/[image_id]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

      Response