BigCommerce Images API

openapi: 3.2.0
info:
  title: Bigcommerce Images API
  version: ''
  contact:
    name: BigCommerce
    url: https://www.bigcommerce.com
    email: support@bigcommerce.com
  termsOfService: https://www.bigcommerce.com/terms
  description: 'Operations tagged Images across 5 of this provider''s published API definitions: catalog-brands-openapi-original.yml, catalog-categories-openapi-original.yml, catalog-product-modifiers-openapi-original.yml, catalog-product-variants-openapi-original.yml, catalog-products-openapi-original.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.bigcommerce.com/stores/{store_hash}/v3
  variables:
    store_hash:
      default: store_hash
      description: Permanent ID of the BigCommerce store.
  description: BigCommerce API Gateway
security:
- X-Auth-Token: []
tags:
- name: Images
paths:
  /catalog/brands/{brand_id}/image:
    parameters:
    - $ref: '#/components/parameters/Accept'
    - $ref: '#/components/parameters/BrandIdParam'
    post:
      tags:
      - Images
      summary: BigCommerce Create a Brand Image
      description: 'Creates a *Brand Image*.


        **Required Fields**

        - image_file: Form posts are the only accepted upload option.


        **Read-Only Fields**

        - id


        Only one image at a time can be created. To update a *Brand Image*, use the [Update a brand](/docs/rest-catalog/brands#update-a-brand) endpoint and an `image_url`.'
      operationId: createBrandImage
      parameters:
      - $ref: '#/components/parameters/ContentType'
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                image_file:
                  type: string
                  format: binary
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                title: Brand Image Response
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      image_url:
                        type: string
                  meta:
                    $ref: '#/components/schemas/metaEmpty_Full'
              example:
                data:
                  image_url: https://cdn11.bigcommerce.com/s-{store_hash}/product_images/k/group_1545334669__76009.png
                meta: {}
        '400':
          description: Bad Request. The requested resource could not be downloaded and may be invalid. Possible reasons include malformed request syntax or the file host blocking requests.
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '404':
          description: The resource was not found.
          content:
            application/json:
              schema:
                title: Not Found
                type: object
                properties:
                  status:
                    type: integer
                    description: '404 HTTP status code.

                      '
                  title:
                    type: string
                    description: The error title describing the particular error.
                  type:
                    type: string
                  instance:
                    type: string
                description: Error payload for the BigCommerce API.
        '422':
          description: Image was not valid. This is the result of a missing `image_file` field, or of an incorrect file type. See the response for more details.
          content:
            application/json:
              schema:
                title: Error Response
                type: object
                properties:
                  errors:
                    title: Detailed Errors
                    type: object
                    properties: {}
                    additionalProperties: true
                  instance:
                    type: string
                  status:
                    type: integer
                    description: 'The HTTP status code.

                      '
                  title:
                    type: string
                    description: 'The error title describing the particular error.

                      '
                  type:
                    type: string
    delete:
      tags:
      - Images
      summary: BigCommerce Delete a Brand Image
      description: Deletes a *Brand Image*.
      operationId: deleteBrandImage
      responses:
        '204':
          description: ''
          content: {}
    servers:
    - url: https://api.bigcommerce.com/stores/{store_hash}/v3
      variables:
        store_hash:
          default: store_hash
          description: Permanent ID of the BigCommerce store.
      description: BigCommerce API Gateway
  /catalog/categories/{category_id}/image:
    parameters:
    - $ref: '#/components/parameters/Accept'
    - $ref: '#/components/parameters/CategoryIdParam'
    post:
      tags:
      - Images
      summary: BigCommerce Create a Category Image
      description: "Create a *Category Image*.\n\n **Required Fields**\n- image_file: Form posts are the only accepted upload option.\n\nOnly one image at a time can be created.\nLimit image size to 1MB.\nTo update a *Category Image*, use the [Update categories](/docs/rest-catalog/category-trees/categories#update-categories) endpoint and an `image_url`."
      operationId: createCategoryImage
      parameters:
      - $ref: '#/components/parameters/ContentType'
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                image_file:
                  type: string
                  format: binary
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                title: Create Image Response
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      image_url:
                        type: string
                  meta:
                    $ref: '#/components/schemas/metaEmpty_Full'
              example:
                data:
                  image_url: https://cdn11.bigcommerce.com/s-{store_hash}/product_images/k/group_1545334669__76009.png
                meta: {}
        '400':
          description: Bad Request. The requested resource could not be downloaded and may be invalid. Possible reasons include malformed request syntax or the file host blocking requests.
          content:
            application/json:
              schema:
                title: Error Response
                type: object
                properties: {}
        '404':
          description: 'The resource was not found.

            '
          content:
            application/json:
              schema:
                title: Not Found
                type: object
                properties:
                  status:
                    type: integer
                    description: '404 HTTP status code.

                      '
                  title:
                    type: string
                    description: The error title describing the particular error.
                  type:
                    type: string
                  instance:
                    type: string
                description: Error payload for the BigCommerce API.
        '422':
          description: 'Image was not valid. This is the result of a missing `image_file` field or an incorrect file type. See the response for more details.

            '
          content:
            application/json:
              schema:
                title: Error Response
                type: object
                properties:
                  errors:
                    title: Detailed Errors
                    type: object
                    properties: {}
                    additionalProperties: true
                  instance:
                    type: string
                  status:
                    type: integer
                    description: 'The HTTP status code.

                      '
                  title:
                    type: string
                    description: 'The error title describing the particular error.

                      '
                  type:
                    type: string
    delete:
      tags:
      - Images
      summary: BigCommerce Delete a Category Image
      description: Deletes a *Category Image*.
      operationId: deleteCategoryImage
      responses:
        '204':
          description: ''
          content: {}
    servers:
    - url: https://api.bigcommerce.com/stores/{store_hash}/v3
      variables:
        store_hash:
          default: store_hash
          description: Permanent ID of the BigCommerce store.
      description: BigCommerce API Gateway
  /catalog/products/{product_id}/modifiers/{modifier_id}/values/{value_id}/image:
    parameters:
    - $ref: '#/components/parameters/Accept'
    - $ref: '#/components/parameters/ProductIdParam'
    - $ref: '#/components/parameters/ModifierIdParam'
    - $ref: '#/components/parameters/ValueIdParam'
    post:
      tags:
      - Images
      summary: BigCommerce Create Product Modifier Image
      description: "Creates a *Modifier Image*.\n\nThe image will show on the storefront when the value is selected.\n\n **Required Fields**\n- image_file: Form posts are the only accepted upload option."
      operationId: createProductModifierImage
      parameters:
      - $ref: '#/components/parameters/ContentType'
      - name: modifier_id
        in: path
        description: 'The ID of the `Modifier`.

          '
        required: true
        schema:
          type: integer
      - name: value_id
        in: path
        description: 'The ID of the `Modifier`.

          '
        required: true
        schema:
          type: integer
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                image_file:
                  type: string
                  format: binary
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                title: Image Response
                type: object
                properties:
                  data:
                    title: Resource Image
                    type: object
                    properties:
                      image_url:
                        type: string
                        description: 'A public URL for a GIF, JPEG, or PNG image. Limit of 8MB per file.

                          '
                    description: An object containing a publicly accessible image URL, or a form post that contains an image file.
                  meta:
                    $ref: '#/components/schemas/metaEmpty_Full'
                description: 'Image Response returns for:

                  * Create Variant Image

                  * Create Modifier Image

                  * Create Category Image

                  * Create Brand Image'
              example:
                data:
                  image_url: https://cdn8.bigcommerce.com/s-id30h7ohwf/product_images/attribute_rule_images/85_source_1536863430.png
                meta: {}
        '400':
          description: Bad Request. The requested resource could not be downloaded and may be invalid. Possible reasons include malformed request syntax or the file host blocking requests.
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '404':
          description: 'The resource was not found.

            '
          content:
            application/json:
              schema:
                title: Not Found
                type: object
                properties:
                  status:
                    type: integer
                    description: '404 HTTP status code.

                      '
                  title:
                    type: string
                    description: The error title describing the particular error.
                  type:
                    type: string
                  instance:
                    type: string
                description: Error payload for the BigCommerce API.
        '422':
          description: 'Modifier image was not valid. This is the result of missing `image_file` fields, or of a non-URL value for the `image_file` field. See the response for more details.

            '
          content:
            application/json:
              schema:
                title: Error Response
                type: object
                properties:
                  errors:
                    title: Detailed Errors
                    type: object
                    properties: {}
                    additionalProperties: true
                  instance:
                    type: string
                  status:
                    type: integer
                    description: 'The HTTP status code.

                      '
                  title:
                    type: string
                    description: 'The error title describing the particular error.

                      '
                  type:
                    type: string
    servers:
    - url: https://api.bigcommerce.com/stores/{store_hash}/v3
      variables:
        store_hash:
          default: store_hash
          description: Permanent ID of the BigCommerce store.
      description: BigCommerce API Gateway
  /catalog/products/{product_id}/variants/{variant_id}/image:
    parameters:
    - $ref: '#/components/parameters/Accept'
    - $ref: '#/components/parameters/ProductIdParam_2'
    - $ref: '#/components/parameters/VariantIdParam'
    post:
      tags:
      - Images
      summary: BigCommerce Create a Product Variant Image
      description: "Creates a *Variant Image*.\n\nOnly one image can be explicitly associated with a Variant. If the Variant already has an associated image, overwrites the existing Variant Image.\n\nThe image displays on the storefront when the Variant is selected.\n\n **Required Fields**\n- image_file: Form posts. Files larger than 1 MB are not accepted\n- image_url: Any publicly available URL"
      operationId: createProductVariantImage
      parameters:
      - $ref: '#/components/parameters/ContentType'
      - name: variant_id
        in: path
        description: 'ID of the variant on a product, or on an associated Price List Record.

          '
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                image_url:
                  type: string
                  description: 'A public URL for a GIF, JPEG, or PNG image. Limit of 8MB per file.

                    '
              description: An object containing a publicly accessible image URL, or a form post that contains an image file.
          multipart/form-data:
            schema:
              type: object
              properties:
                image_url:
                  type: string
                  description: 'A public URL for a GIF, JPEG, or PNG image. Limit of 8MB per file.

                    '
              description: An object containing a publicly accessible image URL, or a form post that contains an image file.
        required: false
      responses:
        '200':
          description: '`image_url` is returned for both `image_file` and `image_url`.'
          content:
            application/json:
              schema:
                title: Image Response
                type: object
                properties:
                  data:
                    title: Resource Image
                    type: object
                    properties:
                      image_url:
                        type: string
                        description: 'A public URL for a GIF, JPEG, or PNG image. Limit of 8MB per file.

                          '
                    description: An object containing a publicly accessible image URL, or a form post that contains an image file.
                  meta:
                    $ref: '#/components/schemas/metaEmpty_Full'
                description: 'Image Response returns for:

                  * Create Variant Image

                  * Create Modifier Image

                  * Create Category Image

                  * Create Brand Image'
              example:
                data:
                  image_url: https://cdn8.bigcommerce.com/s-id30h7ohwf/product_images/attribute_rule_images/85_source_1536863430.png
                meta: {}
        '400':
          description: Bad Request. The requested resource could not be downloaded and may be invalid. Possible reasons include malformed request syntax or the file host blocking requests.
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '404':
          description: 'The resource was not found.

            '
          content:
            application/json:
              schema:
                title: Not Found
                type: object
                properties:
                  status:
                    type: integer
                    description: '404 HTTP status code.

                      '
                  title:
                    type: string
                    description: The error title describing the particular error.
                  type:
                    type: string
                  instance:
                    type: string
                description: Error payload for the BigCommerce API.
        '422':
          description: 'Image was not valid. This is the result of a missing `image_file` field or of an incorrect file type. See the response for more details.

            '
          content:
            application/json:
              schema:
                title: Error Response
                type: object
                properties:
                  errors:
                    title: Detailed Errors
                    type: object
                    properties: {}
                    additionalProperties: true
                  instance:
                    type: string
                  status:
                    type: integer
                    description: 'The HTTP status code.

                      '
                  title:
                    type: string
                    description: 'The error title describing the particular error.

                      '
                  type:
                    type: string
        '500':
          description: Returns for an `image_file` larger than 1 MB.
          content:
            application/json:
              schema:
                title: Error Response
                type: object
                properties:
                  errors:
                    title: Detailed Errors
                    type: object
                    properties: {}
                    additionalProperties: true
                  instance:
                    type: string
                  status:
                    type: integer
                    description: 'The HTTP status code.

                      '
                  title:
                    type: string
                    description: 'The error title describing the particular error.

                      '
                  type:
                    type: string
      x-codegen-request-body-name: body
    servers:
    - url: https://api.bigcommerce.com/stores/{store_hash}/v3
      variables:
        store_hash:
          default: store_hash
          description: Permanent ID of the BigCommerce store.
      description: BigCommerce API Gateway
  /catalog/products/{product_id}/images:
    parameters:
    - $ref: '#/components/parameters/Accept'
    - $ref: '#/components/parameters/ProductIdParam'
    get:
      tags:
      - Images
      summary: BigCommerce Get All Product Images
      description: Returns a list of *Product Images*. Optional parameters can be passed in.
      operationId: getProductImages
      parameters:
      - name: page
        in: query
        description: Specifies the page number in a limited (paginated) list of products.
        schema:
          type: integer
      - name: limit
        in: query
        description: Controls the number of items per page in a limited (paginated) list of products.
        schema:
          type: integer
      - name: include_fields
        in: query
        description: Fields to include, in a comma-separated list. The ID and the specified fields will be returned.
        schema:
          type: string
      - name: exclude_fields
        in: query
        description: Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                title: Product Image Collection Response
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/productImage_Full'
                  meta:
                    $ref: '#/components/schemas/metaCollection_Full'
                description: 'Response payload for the BigCommerce API.

                  '
              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
        '204':
          description: 'There are not any images on this product.

            '
          content: {}
        '404':
          description: 'The product ID does not exist.

            '
          content:
            application/json:
              schema:
                title: Not Found
                type: object
                properties:
                  status:
                    type: integer
                    description: '404 HTTP status code.

                      '
                  title:
                    type: string
                    description: The error title describing the particular error.
                  type:
                    type: string
                  instance:
                    type: string
                description: Error payload for the BigCommerce API.
    post:
      tags:
      - Images
      summary: BigCommerce Create a Product Image
      description: "Creates a *Product Image*.\n\n **Required Fields**\n- `image_file`, or\n- `image_url`\n\n**Usage Notes**\n- `image_url` - `255` character limit\n- For file uploads, use the `multipart/form-data` media type.\n- You can create only one image at a time. A product can have up to 1000 images.\n- Supported image file types are BMP, GIF, JPEG, PNG, WBMP, XBM, and WEBP.\n- Each image file or image uploaded by URL can be up to 8 MB."
      operationId: createProductImage
      parameters:
      - $ref: '#/components/parameters/ContentType'
      requestBody:
        content:
          application/json:
            schema:
              title: Product Image Post
              description: The model for a POST to create an image on a product.
              allOf:
              - title: Product Image Base
                type: object
                properties:
                  product_id:
                    type: integer
                    description: 'The unique numeric identifier for the product with which the image is associated.

                      '
                  url_zoom:
                    readOnly: true
                    type: string
                    description: '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:
                    readOnly: true
                    type: string
                    description: 'The standard URL for this image. By default, this is used for product-page images.

                      '
                  url_thumbnail:
                    readOnly: true
                    type: string
                    description: 'The thumbnail URL for this image. By default, this is the image size used on the category page and in side panels.

                      '
                  url_tiny:
                    readOnly: true
                    type: string
                    description: '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:
                    type: string
                    description: 'The date on which the product image was modified.

                      '
                    format: date-time
                  is_thumbnail:
                    type: boolean
                    description: 'Flag for identifying whether the image is used as the productʼs thumbnail.

                      '
                  sort_order:
                    maximum: 2147483647
                    minimum: -2147483648
                    type: integer
                    description: '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_order`s reordered.

                      '
                  description:
                    type: string
                    description: 'The description for the image.

                      '
                description: Common ProductImage properties.
              - type: object
                properties:
                  image_url:
                    type: string
                    description: 'Must be a fully qualified URL path, including protocol. Limit of 8MB per file.

                      '
                  image_file:
                    type: string
                    description: '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.

                      '
          multipart/form-data:
            schema:
              title: Product Image Post
              description: The model for a POST to create an image on a product.
              allOf:
              - title: Product Image Base
                type: object
                properties:
                  id:
                    type: integer
                    description: 'The unique numeric ID of the image; increments sequentially.

                      '
                  product_id:
                    type: integer
                    description: 'The unique numeric identifier for the product with which the image is associated.

                      '
                  url_zoom:
                    readOnly: true
                    type: string
                    description: '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:
                    readOnly: true
                    type: string
                    description: 'The standard URL for this image. By default, this is used for product-page images.

                      '
                  url_thumbnail:
                    readOnly: true
                    type: string
                    description: 'The thumbnail URL for this image. By default, this is the image size used on the category page and in side panels.

                      '
                  url_tiny:
                    readOnly: true
                    type: string
                    description: '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:
                    type: string
                    description: 'The date on which the product image was modified.

                      '
                    format: date-time
                  is_thumbnail:
                    type: boolean
                    description: 'Flag for identifying whether the image is used as the productʼs thumbnail.

                      '
                  sort_order:
                    maximum: 2147483647
                    minimum: -2147483648
                    type: integer
                    description: '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_order`s reordered.

                      '
                  description:
                    type: string
                    description: 'The description for the image.

                      '
                description: Common ProductImage properties.
              - type: object
                properties:
                  image_url:
                    type: string
                    description: 'Must be a fully qualified URL path, including protocol. Limit of 8MB per file.

                      '
                  image_file:
                    type: string
                    description: 'The local path to the original image file uploaded to BigCommerce. A `multipart/form-data` media type.


                      Must be sent as a multipart/f

# --- truncated at 32 KB (64 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bigcommerce/refs/heads/main/openapi/bigcommerce-images-api-openapi.yml