openapi: 3.1.0
info:
  title: 'Admin Catalog: Product Variants'
  version: 1.0.0
paths:
  /stores/{store_hash}/v3/catalog/products/{product_id}/variants:
    get:
      operationId: getProductVariants
      summary: List Product Variants
      description: Returns a list of product variants. Optional parameters can be passed in.
      tags:
        - productVariants
      parameters:
        - name: product_id
          in: path
          description: >
            The ID of the `Product` to which the resource belongs. Product variant metafield endpoints that have the
            `product_id` in the request path are successful as long as the parameter is not empty. The `product_id`
            segment is there only for path consistency.
          required: true
          schema:
            type: integer
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: include_fields
          in: query
          description: Fields to include, in a comma-separated list. The ID and the specified fields will be returned.
          required: false
          schema:
            type: array
            items:
              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.
          required: false
          schema:
            type: array
            items:
              type: string
        - name: page
          in: query
          description: |
            Specifies the page number in a limited (paginated) list of products.
          required: false
          schema:
            type: integer
        - name: limit
          in: query
          description: |
            Controls the number of items per page in a limited (paginated) list of products.
          required: false
          schema:
            type: integer
        - name: X-Auth-Token
          in: header
          description: >-
            ### OAuth scopes


            | UI Name | Permission | Parameter |

            |:--------|:-----------|:----------|

            |  Products | modify | `store_v2_products` |

            |  Products | read-only | `store_v2_products_read_only` |


            ### Authentication header


            | Header | Argument | Description |

            |:-------|:---------|:------------|

            | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our
            [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


            ### Further reading


            For example requests and more information about authenticating BigCommerce APIs, see [Authentication and
            Example
            Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests).


            For more about BigCommerce OAuth scopes, see our [Guide to API
            Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes).


            For a list of API status codes, see [API Status
            Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: >-
            The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response
            body.
          required: true
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product variants_getProductVariants_Response_200'
        '404':
          description: |
            The resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetProductVariantsRequestNotFoundError'
    post:
      operationId: createProductVariant
      summary: Create Product Variant
      description: >-
        Creates a product variant.


        **Required Fields**

        * sku

        * option_values


        **Read-Only Fields**

        * id


        **Limits**

        * 600 SKUs per product limit.

        * 255 characters SKU length limit.


        Variants need to be created one at a time using this endpoint. To use a variant array, create products, and
        variants in the same call use the [Create
        Products](/developer/api-reference/rest/admin/catalog/products/create-product) endpoint during the initial
        product creation. To obtain the `option_values` to include in this request, use the [Create a product variant
        option](/developer/api-reference/rest/admin/catalog/product-variant-options/create-product-variant-option)
        endpoint.
      tags:
        - productVariants
      parameters:
        - name: product_id
          in: path
          description: >
            The ID of the `Product` to which the resource belongs. Product variant metafield endpoints that have the
            `product_id` in the request path are successful as long as the parameter is not empty. The `product_id`
            segment is there only for path consistency.
          required: true
          schema:
            type: integer
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: X-Auth-Token
          in: header
          description: >-
            ### OAuth scopes


            | UI Name | Permission | Parameter |

            |:--------|:-----------|:----------|

            |  Products | modify | `store_v2_products` |

            |  Products | read-only | `store_v2_products_read_only` |


            ### Authentication header


            | Header | Argument | Description |

            |:-------|:---------|:------------|

            | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our
            [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


            ### Further reading


            For example requests and more information about authenticating BigCommerce APIs, see [Authentication and
            Example
            Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests).


            For more about BigCommerce OAuth scopes, see our [Guide to API
            Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes).


            For a list of API status codes, see [API Status
            Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: >-
            The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response
            body.
          required: true
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product variants_createProductVariant_Response_200'
        '404':
          description: |
            The resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateProductVariantRequestNotFoundError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/productVariant_Post'
  /stores/{store_hash}/v3/catalog/products/{product_id}/variants/{variant_id}:
    get:
      operationId: getProductVariant
      summary: Get Product Variant
      description: Returns a single product variant. Optional parameters can be passed in.
      tags:
        - productVariants
      parameters:
        - name: product_id
          in: path
          description: >
            The ID of the `Product` to which the resource belongs. Product variant metafield endpoints that have the
            `product_id` in the request path are successful as long as the parameter is not empty. The `product_id`
            segment is there only for path consistency.
          required: true
          schema:
            type: integer
        - 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
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: include_fields
          in: query
          description: Fields to include, in a comma-separated list. The ID and the specified fields will be returned.
          required: false
          schema:
            type: array
            items:
              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.
          required: false
          schema:
            type: array
            items:
              type: string
        - name: X-Auth-Token
          in: header
          description: >-
            ### OAuth scopes


            | UI Name | Permission | Parameter |

            |:--------|:-----------|:----------|

            |  Products | modify | `store_v2_products` |

            |  Products | read-only | `store_v2_products_read_only` |


            ### Authentication header


            | Header | Argument | Description |

            |:-------|:---------|:------------|

            | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our
            [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


            ### Further reading


            For example requests and more information about authenticating BigCommerce APIs, see [Authentication and
            Example
            Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests).


            For more about BigCommerce OAuth scopes, see our [Guide to API
            Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes).


            For a list of API status codes, see [API Status
            Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: >-
            The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response
            body.
          required: true
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product variants_getProductVariant_Response_200'
        '404':
          description: |
            The resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetProductVariantRequestNotFoundError'
    put:
      operationId: updateProductVariant
      summary: Update Product Variant
      description: Updates a product variant.
      tags:
        - productVariants
      parameters:
        - name: product_id
          in: path
          description: >
            The ID of the `Product` to which the resource belongs. Product variant metafield endpoints that have the
            `product_id` in the request path are successful as long as the parameter is not empty. The `product_id`
            segment is there only for path consistency.
          required: true
          schema:
            type: integer
        - 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
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: X-Auth-Token
          in: header
          description: >-
            ### OAuth scopes


            | UI Name | Permission | Parameter |

            |:--------|:-----------|:----------|

            |  Products | modify | `store_v2_products` |

            |  Products | read-only | `store_v2_products_read_only` |


            ### Authentication header


            | Header | Argument | Description |

            |:-------|:---------|:------------|

            | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our
            [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


            ### Further reading


            For example requests and more information about authenticating BigCommerce APIs, see [Authentication and
            Example
            Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests).


            For more about BigCommerce OAuth scopes, see our [Guide to API
            Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes).


            For a list of API status codes, see [API Status
            Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: >-
            The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response
            body.
          required: true
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product variants_updateProductVariant_Response_200'
        '404':
          description: |
            The resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateProductVariantRequestNotFoundError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/productVariant_Put'
    delete:
      operationId: deleteProductVariant
      summary: Delete Product Variant
      description: Deletes a product variant.
      tags:
        - productVariants
      parameters:
        - name: product_id
          in: path
          description: >
            The ID of the `Product` to which the resource belongs. Product variant metafield endpoints that have the
            `product_id` in the request path are successful as long as the parameter is not empty. The `product_id`
            segment is there only for path consistency.
          required: true
          schema:
            type: integer
        - 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
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: X-Auth-Token
          in: header
          description: >-
            ### OAuth scopes


            | UI Name | Permission | Parameter |

            |:--------|:-----------|:----------|

            |  Products | modify | `store_v2_products` |

            |  Products | read-only | `store_v2_products_read_only` |


            ### Authentication header


            | Header | Argument | Description |

            |:-------|:---------|:------------|

            | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our
            [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


            ### Further reading


            For example requests and more information about authenticating BigCommerce APIs, see [Authentication and
            Example
            Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests).


            For more about BigCommerce OAuth scopes, see our [Guide to API
            Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes).


            For a list of API status codes, see [API Status
            Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: >-
            The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response
            body.
          required: true
          schema:
            type: string
            default: application/json
      responses:
        '204':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties: {}
  /stores/{store_hash}/v3/catalog/variants/metafields:
    get:
      operationId: getVariantsMetafields
      summary: List Product Variant Metafields
      description: Get all variant metafields.
      tags:
        - batchMetafields
      parameters:
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: page
          in: query
          description: |
            Specifies the page number in a limited (paginated) list of products.
          required: false
          schema:
            type: integer
        - name: limit
          in: query
          description: |
            Controls the number of items per page in a limited (paginated) list of products.
          required: false
          schema:
            type: integer
        - name: key
          in: query
          description: Filter based on a metafieldʼs key.
          required: false
          schema:
            type: string
        - name: key:in
          in: query
          description: Filter based on comma-separated metafieldʼs keys. Could be used with vanilla `key` query parameter.
          required: false
          schema:
            type: array
            items:
              type: string
        - name: namespace
          in: query
          description: Filter based on a metafieldʼs namespaces.
          required: false
          schema:
            type: string
        - name: namespace:in
          in: query
          description: >-
            Filter based on comma-separated metafieldʼs namespaces. Could be used with vanilla `namespace` query
            parameter.
          required: false
          schema:
            type: array
            items:
              type: string
        - name: direction
          in: query
          description: |
            Sort direction. Acceptable values are: `asc`, `desc`.
          required: false
          schema:
            $ref: '#/components/schemas/CatalogVariantsMetafieldsGetParametersDirection'
        - name: include_fields
          in: query
          description: Fields to include, in a comma-separated list. The ID and the specified fields will be returned.
          required: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/CatalogVariantsMetafieldsGetParametersIncludeFieldsSchemaItems'
        - name: date_created:min
          in: query
          description: >
            'Query parameter that lets you filter by the minimum date created, for example, `2024-05-14T09:34:00` or
            `2024-05-14`. Returns metafields created after this date.'
          required: false
          schema:
            type: string
        - name: date_created:max
          in: query
          description: >
            'Query parameter that lets you filter by the maximum date created, for example, `2024-05-14T09:34:00` or
            `2024-05-14`. Returns metafields created before this date.'
          required: false
          schema:
            type: string
        - name: date_modified:min
          in: query
          description: >
            'Query parameter that lets you filter by the minimum date modified, for example, `2024-05-14T09:34:00` or
            `2024-05-14`. Returns metafields modified after this date.'
          required: false
          schema:
            type: string
        - name: date_modified:max
          in: query
          description: >
            'Query parameter that lets you filter by the maximum date modified, for example, `2024-05-14T09:34:00` or
            `2024-05-14`. Returns metafields modified before this date.'
          required: false
          schema:
            type: string
        - name: X-Auth-Token
          in: header
          description: >-
            ### OAuth scopes


            | UI Name | Permission | Parameter |

            |:--------|:-----------|:----------|

            |  Products | modify | `store_v2_products` |

            |  Products | read-only | `store_v2_products_read_only` |


            ### Authentication header


            | Header | Argument | Description |

            |:-------|:---------|:------------|

            | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our
            [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


            ### Further reading


            For example requests and more information about authenticating BigCommerce APIs, see [Authentication and
            Example
            Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests).


            For more about BigCommerce OAuth scopes, see our [Guide to API
            Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes).


            For a list of API status codes, see [API Status
            Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: >-
            The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response
            body.
          required: true
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: |
            List of `Metafield` objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetaFieldCollectionResponse'
    post:
      operationId: createVariantsMetafields
      summary: Create Multiple Metafields
      description: Create multiple metafields.
      tags:
        - batchMetafields
      parameters:
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: X-Auth-Token
          in: header
          description: >-
            ### OAuth scopes


            | UI Name | Permission | Parameter |

            |:--------|:-----------|:----------|

            |  Products | modify | `store_v2_products` |

            |  Products | read-only | `store_v2_products_read_only` |


            ### Authentication header


            | Header | Argument | Description |

            |:-------|:---------|:------------|

            | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our
            [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


            ### Further reading


            For example requests and more information about authenticating BigCommerce APIs, see [Authentication and
            Example
            Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests).


            For more about BigCommerce OAuth scopes, see our [Guide to API
            Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes).


            For a list of API status codes, see [API Status
            Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: >-
            The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response
            body.
          required: true
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: |
            List of created `Metafield` objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetaFieldCollectionResponse_POST_PUT'
        '400':
          description: Bad Request. Input is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateVariantsMetafieldsRequestBadRequestError'
        '422':
          description: |
            Response object for metafields creation with partial success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetaFieldCollectionResponsePartialSuccess_POST_PUT'
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CatalogVariantsMetafieldsPostRequestBodyContentApplicationJsonSchemaItems'
    put:
      operationId: updateVariantsMetafields
      summary: Update Multiple Metafields
      description: Create multiple metafields.
      tags:
        - batchMetafields
      parameters:
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: X-Auth-Token
          in: header
          description: >-
            ### OAuth scopes


            | UI Name | Permission | Parameter |

            |:--------|:-----------|:----------|

            |  Products | modify | `store_v2_products` |

            |  Products | read-only | `store_v2_products_read_only` |


            ### Authentication header


            | Header | Argument | Description |

            |:-------|:---------|:------------|

            | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our
            [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


            ### Further reading


            For example requests and more information about authenticating BigCommerce APIs, see [Authentication and
            Example
            Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests).


            For more about BigCommerce OAuth scopes, see our [Guide to API
            Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes).


            For a list of API status codes, see [API Status
            Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: >-
            The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response
            body.
          required: true
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: |
            List of updated `Metafield` objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetaFieldCollectionResponse_POST_PUT'
        '400':
          description: Bad Request. Input is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateVariantsMetafieldsRequestBadRequestError'
        '422':
          description: |
            Response object for metafields creation with partial success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetaFieldCollectionResponsePartialSuccess_POST_PUT'
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CatalogVariantsMetafieldsPutRequestBodyContentApplicationJsonSchemaItems'
    delete:
      operationId: deleteVariantsMetafields
      summary: Delete Multiple Metafields
      description: Delete all variant metafields.
      tags:
        - batchMetafields
      parameters:
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: X-Auth-Token
          in: header
          description: >-
            ### OAuth scopes


            | UI Name | Permission | Parameter |

            |:--------|:-----------|:----------|

            |  Products | modify | `store_v2_products` |

            |  Products | read-only | `store_v2_products_read_only` |


            ### Authentication header


            | Header | Argument | Description |

            |:-------|:---------|:------------|

            | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our
            [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


            ### Further reading


            For example requests and more information about authenticating BigCommerce APIs, see [Authentication and
            Example
            Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests).


            For more about BigCommerce OAuth scopes, see our [Guide to API
            Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes).


            For a list of API status codes, see [API Status
            Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: >-
            The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response
            body.
          required: true
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: |
            Response object for metafields deletion with success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetaFieldCollectionDeleteResponseSuccess'
        '400':
          description: Bad Request. Input is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteVariantsMetafieldsRequestBadRequestError'
        '422':
          description: |
            Response object for metafields deletion with partial success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetaFieldCollectionResponsePartialSuccess_DELETE'
      requestBody:
        description: List of metafield IDs.
        content:
          application/json:
            schema:
              type: array
              items:
                type: integer
  /stores/{store_hash}/v3/catalog/products/{product_id}/variants/{variant_id}/image:
    post:
      operationId: createProductVariantImage
      summary: Create Product Variant Image
      description: >-
        Creates a *Variant Image*.


        Only one image can be explicitly associated with a Variant. If the Variant already has an associated image,
        overwrites the existing Variant Image.


        The image displays on the storefront when the Variant is selected.

         **Required Fields**
        - image_file: Form posts. Files larger than 1 MB are not accepted

        - image_url: Any publicly available URL
      tags:
        - images
      parameters:
        - name: product_id
          in: path
          description: >
            The ID of the `Product` to which the resource belongs. Product variant metafield endpoints that have the
            `product_id` in the request path are successful as long as the parameter is not empty. The `product_id`
            segment is there only for path consistency.
          required: true
          schema:
            type: integer
        - 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
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: X-Auth-Token
          in: header
          description: >-
            ### OAuth scopes


            | UI Name | Permission | Parameter |

            |:--------|:-----------|:----------|

            |  Products | modify | `store_v2_products` |

            |  Products | read-only | `store_v2_products_read_only` |


            ### Authentication header


            | Header | Argument | Description |

            |:-------|:---------|:------------|

            | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our
            [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


            ### Further reading


            For example requests and more information about authenticating BigCommerce APIs, see [Authentication and
            Example
            Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests).


            For more about BigCommerce OAuth scopes, see our [Guide to API
            Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes).


            For a list of API status codes, see [API Status
            Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: >-
            The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response
            body.
          required: true
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: '`image_url` is returned for both `image_file` and `image_url`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Images_createProductVariantImage_Response_200'
        '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:
                $ref: '#/components/schemas/CreateProductVariantImageRequestBadRequestError'
        '404':
          description: |
            The resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateProductVariantImageRequestNotFoundError'
        '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:
                $ref: '#/components/schemas/CreateProductVariantImageRequestUnprocessableEntityError'
        '500':
          description: Returns for an `image_file` larger than 1 MB.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateProductVariantImageRequestInternalServerError'
      requestBody:
        description: An object containing a publicly accessible image URL, or a form post that contains an image file.
        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.
  /stores/{store_hash}/v3/catalog/products/{product_id}/variants/{variant_id}/metafields:
    get:
      operationId: getProductVariantMetafields
      summary: List Product Variant Metafields
      description: Returns a list of product variant *Metafields*. Optional parameters can be passed in.
      tags:
        - metafields
      parameters:
        - name: product_id
          in: path
          description: >
            The ID of the `Product` to which the resource belongs. Product variant metafield endpoints that have the
            `product_id` in the request path are successful as long as the parameter is not empty. The `product_id`
            segment is there only for path consistency.
          required: true
          schema:
            type: integer
        - 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
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: include_fields
          in: query
          description: Fields to include, in a comma-separated list. The ID and the specified fields will be returned.
          required: false
          schema:
            type: array
            items:
              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.
          required: false
          schema:
            type: array
            items:
              type: string
        - name: page
          in: query
          description: |
            Specifies the page number in a limited (paginated) list of products.
          required: false
          schema:
            type: integer
        - name: limit
          in: query
          description: |
            Controls the number of items per page in a limited (paginated) list of products.
          required: false
          schema:
            type: integer
        - name: key
          in: query
          description: Filter based on a metafieldʼs key.
          required: false
          schema:
            type: string
        - name: namespace
          in: query
          description: Filter based on a metafieldʼs namespaces.
          required: false
          schema:
            type: string
        - name: resource_id:in
          in: query
          description: >-
            A comma-separated list of entity ID values that filter results to metafields that belong to one of the
            matching entities.
          required: false
          schema:
            type: string
        - name: X-Auth-Token
          in: header
          description: >-
            ### OAuth scopes


            | UI Name | Permission | Parameter |

            |:--------|:-----------|:----------|

            |  Products | modify | `store_v2_products` |

            |  Products | read-only | `store_v2_products_read_only` |


            ### Authentication header


            | Header | Argument | Description |

            |:-------|:---------|:------------|

            | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our
            [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


            ### Further reading


            For example requests and more information about authenticating BigCommerce APIs, see [Authentication and
            Example
            Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests).


            For more about BigCommerce OAuth scopes, see our [Guide to API
            Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes).


            For a list of API status codes, see [API Status
            Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: >-
            The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response
            body.
          required: true
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Metafields_getProductVariantMetafields_Response_200'
    post:
      operationId: createProductVariantMetafield
      summary: Create Product Variant Metafield
      description: >-
        Creates a product variant *Metafield*.


        **Required Fields:**

        * permission_set

        * namespace

        * key

        * value


        **Read-Only Fields**

        * id


        **Note:** The maxiumum number of metafields allowed on each order, product, category, variant, or brand is 250
        per client ID. For more information, see [Platform
        Limits](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center.
      tags:
        - metafields
      parameters:
        - name: product_id
          in: path
          description: >
            The ID of the `Product` to which the resource belongs. Product variant metafield endpoints that have the
            `product_id` in the request path are successful as long as the parameter is not empty. The `product_id`
            segment is there only for path consistency.
          required: true
          schema:
            type: integer
        - 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
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: X-Auth-Token
          in: header
          description: >-
            ### OAuth scopes


            | UI Name | Permission | Parameter |

            |:--------|:-----------|:----------|

            |  Products | modify | `store_v2_products` |

            |  Products | read-only | `store_v2_products_read_only` |


            ### Authentication header


            | Header | Argument | Description |

            |:-------|:---------|:------------|

            | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our
            [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


            ### Further reading


            For example requests and more information about authenticating BigCommerce APIs, see [Authentication and
            Example
            Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests).


            For more about BigCommerce OAuth scopes, see our [Guide to API
            Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes).


            For a list of API status codes, see [API Status
            Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: >-
            The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response
            body.
          required: true
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Metafields_createProductVariantMetafield_Response_200'
        '400':
          description: Bad Request. Input is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateProductVariantMetafieldRequestBadRequestError'
        '409':
          description: >
            The `Metafield` was in conflict with another `Metafield`. This can be the result of duplicate unique-key
            combinations of the appʼs client id, namespace, key, resource_type, and resource_id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateProductVariantMetafieldRequestConflictError'
        '422':
          description: >
            The `Metafield` was not valid. This is the result of missing required fields, or of invalid data. See the
            response for more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateProductVariantMetafieldRequestUnprocessableEntityError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/metafield_Base'
  /stores/{store_hash}/v3/catalog/products/{product_id}/variants/{variant_id}/metafields/{metafield_id}:
    get:
      operationId: getProductVariantMetafield
      summary: Get Product Variant Metafield
      description: Returns a single product variant *Metafield*. Optional parameters can be passed in.
      tags:
        - metafields
      parameters:
        - name: product_id
          in: path
          description: >
            The ID of the `Product` to which the resource belongs. Product variant metafield endpoints that have the
            `product_id` in the request path are successful as long as the parameter is not empty. The `product_id`
            segment is there only for path consistency.
          required: true
          schema:
            type: integer
        - 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
        - name: metafield_id
          in: path
          description: |
            The ID of the `Metafield`.
          required: true
          schema:
            type: integer
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: include_fields
          in: query
          description: Fields to include, in a comma-separated list. The ID and the specified fields will be returned.
          required: false
          schema:
            type: array
            items:
              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.
          required: false
          schema:
            type: array
            items:
              type: string
        - name: X-Auth-Token
          in: header
          description: >-
            ### OAuth scopes


            | UI Name | Permission | Parameter |

            |:--------|:-----------|:----------|

            |  Products | modify | `store_v2_products` |

            |  Products | read-only | `store_v2_products_read_only` |


            ### Authentication header


            | Header | Argument | Description |

            |:-------|:---------|:------------|

            | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our
            [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


            ### Further reading


            For example requests and more information about authenticating BigCommerce APIs, see [Authentication and
            Example
            Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests).


            For more about BigCommerce OAuth scopes, see our [Guide to API
            Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes).


            For a list of API status codes, see [API Status
            Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: >-
            The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response
            body.
          required: true
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Metafields_getProductVariantMetafield_Response_200'
        '404':
          description: |
            The resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetProductVariantMetafieldRequestNotFoundError'
    put:
      operationId: updateProductVariantMetafield
      summary: Update Product Variant Metafields
      description: "Updates a product variant *Metafield*.\n\n**Required Fields:**\n* none\n\n**Read-Only Fields**\n* id\n* These fields can only be modified by the app (API credentials) that created the metafield:\n\t* namespace\n\t* key\n\t* permission_set\n\n**Usage Notes**\n* Attempting to modify `namespace`, `key`, and `permission_set` fields using a client ID different from the one used to create those metafields will result in a 403 error message. "
      tags:
        - metafields
      parameters:
        - name: product_id
          in: path
          description: >
            The ID of the `Product` to which the resource belongs. Product variant metafield endpoints that have the
            `product_id` in the request path are successful as long as the parameter is not empty. The `product_id`
            segment is there only for path consistency.
          required: true
          schema:
            type: integer
        - 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
        - name: metafield_id
          in: path
          description: |
            The ID of the `Metafield`.
          required: true
          schema:
            type: integer
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: X-Auth-Token
          in: header
          description: >-
            ### OAuth scopes


            | UI Name | Permission | Parameter |

            |:--------|:-----------|:----------|

            |  Products | modify | `store_v2_products` |

            |  Products | read-only | `store_v2_products_read_only` |


            ### Authentication header


            | Header | Argument | Description |

            |:-------|:---------|:------------|

            | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our
            [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


            ### Further reading


            For example requests and more information about authenticating BigCommerce APIs, see [Authentication and
            Example
            Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests).


            For more about BigCommerce OAuth scopes, see our [Guide to API
            Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes).


            For a list of API status codes, see [API Status
            Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: >-
            The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response
            body.
          required: true
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Metafields_updateProductVariantMetafield_Response_200'
        '400':
          description: Bad Request. Input is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateProductVariantMetafieldRequestBadRequestError'
        '404':
          description: |
            The resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateProductVariantMetafieldRequestNotFoundError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/metafield_Base'
    delete:
      operationId: deleteProductVariantMetafield
      summary: Delete Product Variant Metafield
      description: Deletes a product variant *Metafield*.
      tags:
        - metafields
      parameters:
        - name: product_id
          in: path
          description: >
            The ID of the `Product` to which the resource belongs. Product variant metafield endpoints that have the
            `product_id` in the request path are successful as long as the parameter is not empty. The `product_id`
            segment is there only for path consistency.
          required: true
          schema:
            type: integer
        - 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
        - name: metafield_id
          in: path
          description: |
            The ID of the `Metafield`.
          required: true
          schema:
            type: integer
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: X-Auth-Token
          in: header
          description: >-
            ### OAuth scopes


            | UI Name | Permission | Parameter |

            |:--------|:-----------|:----------|

            |  Products | modify | `store_v2_products` |

            |  Products | read-only | `store_v2_products_read_only` |


            ### Authentication header


            | Header | Argument | Description |

            |:-------|:---------|:------------|

            | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our
            [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


            ### Further reading


            For example requests and more information about authenticating BigCommerce APIs, see [Authentication and
            Example
            Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests).


            For more about BigCommerce OAuth scopes, see our [Guide to API
            Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes).


            For a list of API status codes, see [API Status
            Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: >-
            The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response
            body.
          required: true
          schema:
            type: string
            default: application/json
      responses:
        '204':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '404':
          description: |
            The resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteProductVariantMetafieldRequestNotFoundError'
  /stores/{store_hash}/v3/catalog/variants:
    get:
      operationId: getVariants
      summary: List Variants
      description: Returns a list of all variants in your catalog. Optional parameters can be passed in.
      tags:
        - variantsBatch
      parameters:
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: id
          in: query
          description: Filter items by variant ID.
          required: false
          schema:
            type: integer
        - name: sku
          in: query
          description: >-
            Filter items by variant SKU. To filter by product / base variant SKU, see [Get all
            products](/developer/api-reference/rest/admin/catalog/products/get-products). 
          required: false
          schema:
            type: string
        - name: upc
          in: query
          description: |
            Filter items by UPC.
          required: false
          schema:
            type: string
        - name: include_fields
          in: query
          description: Fields to include, in a comma-separated list. The ID and the specified fields will be returned.
          required: false
          schema:
            type: array
            items:
              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.
          required: false
          schema:
            type: array
            items:
              type: string
        - name: page
          in: query
          description: |
            Specifies the page number in a limited (paginated) list of products.
          required: false
          schema:
            type: integer
        - name: limit
          in: query
          description: |
            Controls the number of items per page in a limited (paginated) list of products.
          required: false
          schema:
            type: integer
        - name: product_id:in
          in: query
          description: A comma-separated list of IDs of products you want to request. For example, `?product_id:in=77,80,81`.
          required: false
          schema:
            type: array
            items:
              type: integer
        - name: X-Auth-Token
          in: header
          description: >-
            ### OAuth scopes


            | UI Name | Permission | Parameter |

            |:--------|:-----------|:----------|

            |  Products | modify | `store_v2_products` |

            |  Products | read-only | `store_v2_products_read_only` |


            ### Authentication header


            | Header | Argument | Description |

            |:-------|:---------|:------------|

            | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our
            [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


            ### Further reading


            For example requests and more information about authenticating BigCommerce APIs, see [Authentication and
            Example
            Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests).


            For more about BigCommerce OAuth scopes, see our [Guide to API
            Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes).


            For a list of API status codes, see [API Status
            Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: >-
            The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response
            body.
          required: true
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Variants (Batch)_getVariants_Response_200'
        '404':
          description: The resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetVariantsRequestNotFoundError'
    put:
      operationId: updateVariantsBatch
      summary: Update Variants (batch)
      description: |-
        Updates a batch of `variant` objects. Currently the limit is 50 variants however this is subject to change.

        **Required Fields**

        To update an existing variant:
        * id (variant ID)

        To create a new variant:
        * product_id
        * sku
        * option_values
          - id (option_value ID - Example: 146)
          - option_id (Option ID - Example: 151)
      tags:
        - variantsBatch
      parameters:
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: X-Auth-Token
          in: header
          description: >-
            ### OAuth scopes


            | UI Name | Permission | Parameter |

            |:--------|:-----------|:----------|

            |  Products | modify | `store_v2_products` |

            |  Products | read-only | `store_v2_products_read_only` |


            ### Authentication header


            | Header | Argument | Description |

            |:-------|:---------|:------------|

            | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our
            [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


            ### Further reading


            For example requests and more information about authenticating BigCommerce APIs, see [Authentication and
            Example
            Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests).


            For more about BigCommerce OAuth scopes, see our [Guide to API
            Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes).


            For a list of API status codes, see [API Status
            Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: >-
            The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response
            body.
          required: true
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Variants (Batch)_updateVariantsBatch_Response_200'
        '422':
          description: |
            This is the result of missing required fields, or of invalid data. See the response for more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateVariantsBatchRequestUnprocessableEntityError'
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CatalogVariantsPutRequestBodyContentApplicationJsonSchemaItems'
servers:
  - url: https://api.bigcommerce.com
    description: https://api.bigcommerce.com
components:
  schemas:
    productVariantOptionValue_Full:
      type: object
      properties:
        id:
          type: integer
          description: '`option_value` ID.'
        option_id:
          type: integer
          description: '`option` ID.'
        option_display_name:
          type: string
          description: |
            The name of the option.
        label:
          type: string
          description: |
            The label of the option value.
      title: productVariantOptionValue_Full
    productVariant_Full:
      type: object
      properties:
        cost_price:
          type:
            - number
            - 'null'
          format: double
          description: >-
            The cost price of the variant. It is not affected by Price List prices. This value displays as null in the
            control panel when `cost_price` equals zero.
        price:
          type:
            - number
            - 'null'
          format: double
          description: >-
            This variant’s base price on the storefront. If a Price List ID is used, the Price List value will be used.
            If a Price List ID is not used, and this value is `null`, the product’s default price (set in the Product
            resource’s `price` field) will be used as the base price.
        sale_price:
          type:
            - number
            - 'null'
          format: double
          description: >-
            This variant’s sale price on the storefront. If a Price List ID is used, the Price List value will be used.
            If a Price List ID is not used, and this value is null, the product’s sale price (set in the Product
            resource’s `price` field) will be used as the sale price.
        retail_price:
          type:
            - number
            - 'null'
          format: double
          description: >-
            This variant’s retail price on the storefront. If a Price List ID is used, the Price List value will be
            used. If a Price List ID is not used, and this value is null, the product’s retail price (set in the Product
            resource’s `price` field) will be used as the retail price.
        weight:
          type:
            - number
            - 'null'
          format: double
          description: >-
            This variant’s base weight on the storefront. If this value is null, the product’s default weight (set in
            the Product resource’s weight field) will be used as the base weight.
        width:
          type:
            - number
            - 'null'
          format: double
          description: >
            Width of the variant, which can be used when calculating shipping costs. If this value is `null`, the
            productʼs default width (set in the Product resourceʼs `width` field) will be used as the base width.
        height:
          type:
            - number
            - 'null'
          format: double
          description: >
            Height of the variant, which can be used when calculating shipping costs. If this value is `null`, the
            productʼs default height (set in the Product resourceʼs `height` field) will be used as the base height.
        depth:
          type:
            - number
            - 'null'
          format: double
          description: >
            Depth of the variant, which can be used when calculating shipping costs. If this value is `null`, the
            productʼs default depth (set in the Product resourceʼs `depth` field) will be used as the base depth.
        is_free_shipping:
          type: boolean
          description: >
            Flag used to indicate whether the variant has free shipping. If `true`, the shipping cost for the variant
            will be zero.
        fixed_cost_shipping_price:
          type:
            - number
            - 'null'
          format: double
          description: >
            A fixed shipping cost for the variant. If defined, this value will be used during checkout instead of normal
            shipping-cost calculation.
        purchasing_disabled:
          type: boolean
          description: If `true`, this variant will not be purchasable on the storefront.
        purchasing_disabled_message:
          type: string
          description: If `purchasing_disabled` is `true`, this message should show on the storefront when the variant is selected.
        upc:
          type:
            - string
            - 'null'
          description: The UPC code used in feeds for shopping comparison sites and external channel integrations.
        image_url:
          type: string
          description: Publicly available image url
        inventory_level:
          type:
            - integer
            - 'null'
          description: >-
            Inventory level for the variant, which is used when the product’s inventory_tracking is set to `variant`.
            The Catalog API returns the inventory for only the default location.


            The inventory for a variant cannot exceed 2,147,483,647 in the catalog. The sum of the variant inventories,
            or the total inventory for a product, cannot exceed 2,147,483,647. 


            If you exceed the limit, the store sets the variant inventory to the limit if no other variant inventories
            are set. If other variant inventories are set, the store does not save the variant inventory rather than
            setting the variant inventory to the remaining limit.


            The Catalog API handles limits in a different way than the Inventory API. For more information, see [Limit
            handling](/developer/docs/admin/catalog-and-inventory/inventory-adjustments#limit-handling-in-inventory-versus-catalog-api). 
        inventory_warning_level:
          type:
            - integer
            - 'null'
          description: When the variant hits this inventory level, it is considered low stock.
        bin_picking_number:
          type:
            - string
            - 'null'
          description: Identifies where in a warehouse the variant is located.
        mpn:
          type:
            - string
            - 'null'
          description: The Manufacturer Part Number (MPN) for the variant.
        gtin:
          type:
            - string
            - 'null'
        id:
          type: integer
        product_id:
          type: integer
        sku:
          type: string
        sku_id:
          type:
            - integer
            - 'null'
          description: Read-only reference to v2 APIʼs SKU ID. Null if it is a base variant.
        option_values:
          type: array
          items:
            $ref: '#/components/schemas/productVariantOptionValue_Full'
          description: >-
            Array of option and option values IDs that make up this variant. Will be empty if the variant is the
            productʼs base variant.
        calculated_price:
          type: number
          format: double
          description: >
            The price of the variant as seen on the storefront. This price takes into account `sale_price` and any price
            adjustment rules that are applicable to this variant.
        calculated_weight:
          type: number
          format: double
      title: productVariant_Full
    PaginationFullLinks:
      type: object
      properties:
        previous:
          type: string
          description: |
            Link to the previous page returned in the response.
        current:
          type: string
          description: |
            Link to the current page returned in the response.
        next:
          type: string
          description: |
            Link to the next page returned in the response.
      description: |
        Pagination links for the previous and next parts of the whole collection.
      title: PaginationFullLinks
    pagination_Full:
      type: object
      properties:
        total:
          type: integer
          description: |
            Total number of items in the result set.
        count:
          type: integer
          description: |
            Total number of items in the collection response.
        per_page:
          type: integer
          description: |
            The amount of items returned in the collection per page, controlled by the limit parameter.
        current_page:
          type: integer
          description: |
            The page you are currently on within the collection.
        total_pages:
          type: integer
          description: |
            The total number of pages in the collection.
        links:
          $ref: '#/components/schemas/PaginationFullLinks'
          description: |
            Pagination links for the previous and next parts of the whole collection.
      description: Data about the response, including pagination and collection totals.
      title: pagination_Full
    metaCollection_Full:
      type: object
      properties:
        pagination:
          $ref: '#/components/schemas/pagination_Full'
      description: Data about the response, including pagination and collection totals.
      title: metaCollection_Full
    Product variants_getProductVariants_Response_200:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/productVariant_Full'
        meta:
          $ref: '#/components/schemas/metaCollection_Full'
      title: Product variants_getProductVariants_Response_200
    GetProductVariantsRequestNotFoundError:
      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.
      title: GetProductVariantsRequestNotFoundError
    productVariant_Post:
      type: object
      properties:
        cost_price:
          type:
            - number
            - 'null'
          format: double
          description: >-
            The cost price of the variant. It is not affected by Price List prices. This value displays as null in the
            control panel when `cost_price` equals zero.
        price:
          type:
            - number
            - 'null'
          format: double
          description: >-
            This variant’s base price on the storefront. If a Price List ID is used, the Price List value will be used.
            If a Price List ID is not used, and this value is `null`, the product’s default price (set in the Product
            resource’s `price` field) will be used as the base price.
        sale_price:
          type:
            - number
            - 'null'
          format: double
          description: >-
            This variant’s sale price on the storefront. If a Price List ID is used, the Price List value will be used.
            If a Price List ID is not used, and this value is null, the product’s sale price (set in the Product
            resource’s `price` field) will be used as the sale price.
        retail_price:
          type:
            - number
            - 'null'
          format: double
          description: >-
            This variant’s retail price on the storefront. If a Price List ID is used, the Price List value will be
            used. If a Price List ID is not used, and this value is null, the product’s retail price (set in the Product
            resource’s `price` field) will be used as the retail price.
        weight:
          type:
            - number
            - 'null'
          format: double
          description: >-
            This variant’s base weight on the storefront. If this value is null, the product’s default weight (set in
            the Product resource’s weight field) will be used as the base weight.
        width:
          type:
            - number
            - 'null'
          format: double
          description: >
            Width of the variant, which can be used when calculating shipping costs. If this value is `null`, the
            productʼs default width (set in the Product resourceʼs `width` field) will be used as the base width.
        height:
          type:
            - number
            - 'null'
          format: double
          description: >
            Height of the variant, which can be used when calculating shipping costs. If this value is `null`, the
            productʼs default height (set in the Product resourceʼs `height` field) will be used as the base height.
        depth:
          type:
            - number
            - 'null'
          format: double
          description: >
            Depth of the variant, which can be used when calculating shipping costs. If this value is `null`, the
            productʼs default depth (set in the Product resourceʼs `depth` field) will be used as the base depth.
        is_free_shipping:
          type: boolean
          description: >
            Flag used to indicate whether the variant has free shipping. If `true`, the shipping cost for the variant
            will be zero.
        fixed_cost_shipping_price:
          type:
            - number
            - 'null'
          format: double
          description: >
            A fixed shipping cost for the variant. If defined, this value will be used during checkout instead of normal
            shipping-cost calculation.
        purchasing_disabled:
          type: boolean
          description: If `true`, this variant will not be purchasable on the storefront.
        purchasing_disabled_message:
          type: string
          description: If `purchasing_disabled` is `true`, this message should show on the storefront when the variant is selected.
        upc:
          type:
            - string
            - 'null'
          description: The UPC code used in feeds for shopping comparison sites and external channel integrations.
        inventory_level:
          type:
            - integer
            - 'null'
          description: >-
            Inventory level for the variant, which is used when the product’s inventory_tracking is set to `variant`.
            The Catalog API returns the inventory for only the default location.


            The inventory for a variant cannot exceed 2,147,483,647 in the catalog. The sum of the variant inventories,
            or the total inventory for a product, cannot exceed 2,147,483,647. 


            If you exceed the limit, the store sets the variant inventory to the limit if no other variant inventories
            are set. If other variant inventories are set, the store does not save the variant inventory rather than
            setting the variant inventory to the remaining limit.


            The Catalog API handles limits in a different way than the Inventory API. For more information, see [Limit
            handling](/developer/docs/admin/catalog-and-inventory/inventory-adjustments#limit-handling-in-inventory-versus-catalog-api). 
        inventory_warning_level:
          type:
            - integer
            - 'null'
          description: When the variant hits this inventory level, it is considered low stock.
        bin_picking_number:
          type:
            - string
            - 'null'
          description: Identifies where in a warehouse the variant is located.
        image_url:
          type: string
          description: Publicly available image url
        gtin:
          type:
            - string
            - 'null'
          description: Global Trade Item Number
        mpn:
          type:
            - string
            - 'null'
          description: Manufacturer Part Number
        product_id:
          type: integer
        sku:
          type: string
        option_values:
          type: array
          items:
            $ref: '#/components/schemas/productVariantOptionValue_Full'
          description: >-
            Array of option and option values IDs that make up this variant. Will be empty if the variant is the
            productʼs base variant.
      description: |
        The model for a POST to create variants on a product.
      title: productVariant_Post
    metaEmpty_Full:
      type: object
      properties: {}
      description: Response metadata.
      title: metaEmpty_Full
    Product variants_createProductVariant_Response_200:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/productVariant_Full'
        meta:
          $ref: '#/components/schemas/metaEmpty_Full'
      title: Product variants_createProductVariant_Response_200
    CreateProductVariantRequestNotFoundError:
      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.
      title: CreateProductVariantRequestNotFoundError
    Product variants_getProductVariant_Response_200:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/productVariant_Full'
        meta:
          $ref: '#/components/schemas/metaEmpty_Full'
      title: Product variants_getProductVariant_Response_200
    GetProductVariantRequestNotFoundError:
      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.
      title: GetProductVariantRequestNotFoundError
    productVariant_Put:
      type: object
      properties:
        cost_price:
          type:
            - number
            - 'null'
          format: double
          description: >-
            The cost price of the variant. It is not affected by Price List prices. This value displays as null in the
            control panel when `cost_price` equals zero.
        price:
          type:
            - number
            - 'null'
          format: double
          description: >-
            This variant’s base price on the storefront. If a Price List ID is used, the Price List value will be used.
            If a Price List ID is not used, and this value is `null`, the product’s default price (set in the Product
            resource’s `price` field) will be used as the base price.
        sale_price:
          type:
            - number
            - 'null'
          format: double
          description: >-
            This variant’s sale price on the storefront. If a Price List ID is used, the Price List value will be used.
            If a Price List ID is not used, and this value is null, the product’s sale price (set in the Product
            resource’s `price` field) will be used as the sale price.
        retail_price:
          type:
            - number
            - 'null'
          format: double
          description: >-
            This variant’s retail price on the storefront. If a Price List ID is used, the Price List value will be
            used. If a Price List ID is not used, and this value is null, the product’s retail price (set in the Product
            resource’s `price` field) will be used as the retail price.
        weight:
          type:
            - number
            - 'null'
          format: double
          description: >-
            This variant’s base weight on the storefront. If this value is null, the product’s default weight (set in
            the Product resource’s weight field) will be used as the base weight.
        width:
          type:
            - number
            - 'null'
          format: double
          description: >
            Width of the variant, which can be used when calculating shipping costs. If this value is `null`, the
            productʼs default width (set in the Product resourceʼs `width` field) will be used as the base width.
        height:
          type:
            - number
            - 'null'
          format: double
          description: >
            Height of the variant, which can be used when calculating shipping costs. If this value is `null`, the
            productʼs default height (set in the Product resourceʼs `height` field) will be used as the base height.
        depth:
          type:
            - number
            - 'null'
          format: double
          description: >
            Depth of the variant, which can be used when calculating shipping costs. If this value is `null`, the
            productʼs default depth (set in the Product resourceʼs `depth` field) will be used as the base depth.
        is_free_shipping:
          type: boolean
          description: >
            Flag used to indicate whether the variant has free shipping. If `true`, the shipping cost for the variant
            will be zero.
        fixed_cost_shipping_price:
          type:
            - number
            - 'null'
          format: double
          description: >
            A fixed shipping cost for the variant. If defined, this value will be used during checkout instead of normal
            shipping-cost calculation.
        purchasing_disabled:
          type: boolean
          description: If `true`, this variant will not be purchasable on the storefront.
        purchasing_disabled_message:
          type: string
          description: If `purchasing_disabled` is `true`, this message should show on the storefront when the variant is selected.
        upc:
          type:
            - string
            - 'null'
          description: The UPC code used in feeds for shopping comparison sites and external channel integrations.
        image_url:
          type: string
          description: Publicly available image url
        inventory_level:
          type:
            - integer
            - 'null'
          description: >-
            Inventory level for the variant, which is used when the product’s inventory_tracking is set to `variant`.
            The Catalog API returns the inventory for only the default location.


            The inventory for a variant cannot exceed 2,147,483,647 in the catalog. The sum of the variant inventories,
            or the total inventory for a product, cannot exceed 2,147,483,647. 


            If you exceed the limit, the store sets the variant inventory to the limit if no other variant inventories
            are set. If other variant inventories are set, the store does not save the variant inventory rather than
            setting the variant inventory to the remaining limit.


            The Catalog API handles limits in a different way than the Inventory API. For more information, see [Limit
            handling](/developer/docs/admin/catalog-and-inventory/inventory-adjustments#limit-handling-in-inventory-versus-catalog-api). 
        inventory_warning_level:
          type:
            - integer
            - 'null'
          description: When the variant hits this inventory level, it is considered low stock.
        bin_picking_number:
          type:
            - string
            - 'null'
          description: Identifies where in a warehouse the variant is located.
        mpn:
          type:
            - string
            - 'null'
          description: The Manufacturer Part Number (MPN) for the variant.
        gtin:
          type:
            - string
            - 'null'
        product_id:
          type: integer
        sku:
          type: string
      description: The model for a PUT to update variants on a product.
      title: productVariant_Put
    Product variants_updateProductVariant_Response_200:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/productVariant_Full'
        meta:
          $ref: '#/components/schemas/metaEmpty_Full'
      title: Product variants_updateProductVariant_Response_200
    UpdateProductVariantRequestNotFoundError:
      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.
      title: UpdateProductVariantRequestNotFoundError
    CatalogVariantsMetafieldsGetParametersDirection:
      type: string
      enum:
        - asc
        - desc
      title: CatalogVariantsMetafieldsGetParametersDirection
    CatalogVariantsMetafieldsGetParametersIncludeFieldsSchemaItems:
      type: string
      enum:
        - resource_id
        - key
        - value
        - namespace
        - permission_set
        - resource_type
        - description
        - owner_client_id
        - date_created
        - date_modified
      title: CatalogVariantsMetafieldsGetParametersIncludeFieldsSchemaItems
    MetafieldPermissionSet:
      type: string
      enum:
        - app_only
        - read
        - write
        - read_and_sf_access
        - write_and_sf_access
      description: |
        Determines the visibility and writeability of the field by other API consumers.
        | Value | Description |
        | :--- | :--- |
        | `app_only` | Private to the app that owns the field. |
        | `read` | Visible to other API consumers. |
        | `write` | Open for reading and writing by other API consumers. |
        | `read_and_sf_access` | Visible to other API consumers, including on the storefront. |
        | `write_and_sf_access` | Open for reading and writing by other API consumers, including on the storefront. |
      title: MetafieldPermissionSet
    MetafieldResourceType:
      type: string
      enum:
        - brand
        - product
        - variant
        - category
        - cart
        - channel
        - location
        - order
        - customer
      description: |
        The type of resource with which the metafield is associated.
      title: MetafieldResourceType
    Metafield:
      type: object
      properties:
        id:
          type: integer
          description: The unique identifier for the metafield.
        key:
          type: string
          description: |
            The name of the field, for example: `location_id`, `color`.
        value:
          type: string
          description: |
            The value of the field, for example: `1`, `blue`.
        namespace:
          type: string
          description: |
            Namespace for the metafield, for organizational purposes.
        permission_set:
          $ref: '#/components/schemas/MetafieldPermissionSet'
          description: >
            Determines the visibility and writeability of the field by other API consumers.

            | Value | Description |

            | :--- | :--- |

            | `app_only` | Private to the app that owns the field. |

            | `read` | Visible to other API consumers. |

            | `write` | Open for reading and writing by other API consumers. |

            | `read_and_sf_access` | Visible to other API consumers, including on the storefront. |

            | `write_and_sf_access` | Open for reading and writing by other API consumers, including on the storefront.
            |
        resource_type:
          $ref: '#/components/schemas/MetafieldResourceType'
          description: |
            The type of resource with which the metafield is associated.
        resource_id:
          type: integer
          description: |
            The unique identifier for the resource with which the metafield is associated.
        description:
          type: string
          description: |
            Description for the metafields.
        date_created:
          type: string
          format: date-time
          description: Date and time of the metafieldʼs creation.
        date_modified:
          type: string
          format: date-time
          description: Date and time when the metafield was last updated.
        owner_client_id:
          type: string
          description: Client ID for the metafieldʼs creator.
      description: |
        Common metafield properties.
      title: Metafield
    CollectionMetaPaginationLinks:
      type: object
      properties:
        previous:
          type: string
          description: |
            Link to the previous page returned in the response.
        current:
          type: string
          description: |
            Link to the current page returned in the response.
        next:
          type: string
          description: |
            Link to the next page returned in the response.
      description: |
        Pagination links for the previous and next parts of the whole collection.
      title: CollectionMetaPaginationLinks
    CollectionMetaPagination:
      type: object
      properties:
        total:
          type: integer
          description: |
            Total number of items in the result set.
        count:
          type: integer
          description: |
            Total number of items in the collection response.
        per_page:
          type: integer
          description: |
            The amount of items returned in the collection per page, controlled by the limit parameter.
        current_page:
          type: integer
          description: |
            The page you are currently on within the collection.
        total_pages:
          type: integer
          description: |
            The total number of pages in the collection.
        links:
          $ref: '#/components/schemas/CollectionMetaPaginationLinks'
          description: |
            Pagination links for the previous and next parts of the whole collection.
      description: Data about the response, including pagination and collection totals.
      title: CollectionMetaPagination
    CollectionMeta:
      type: object
      properties:
        pagination:
          $ref: '#/components/schemas/CollectionMetaPagination'
          description: Data about the response, including pagination and collection totals.
      description: Data about the response, including pagination and collection totals.
      title: CollectionMeta
    MetaFieldCollectionResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Metafield'
        meta:
          $ref: '#/components/schemas/CollectionMeta'
      description: |
        Response payload for the BigCommerce API.
      title: MetaFieldCollectionResponse
    CatalogVariantsMetafieldsPostRequestBodyContentApplicationJsonSchemaItemsPermissionSet:
      type: string
      enum:
        - app_only
        - read
        - write
        - read_and_sf_access
        - write_and_sf_access
      description: |
        Determines the visibility and writeability of the field by other API consumers.
        | Value | Description |
        | :--- | :--- |
        | `app_only` | Private to the app that owns the field. |
        | `read` | Visible to other API consumers. |
        | `write` | Open for reading and writing by other API consumers. |
        | `read_and_sf_access` | Visible to other API consumers, including on the storefront. |
        | `write_and_sf_access` | Open for reading and writing by other API consumers, including on the storefront. |
      title: CatalogVariantsMetafieldsPostRequestBodyContentApplicationJsonSchemaItemsPermissionSet
    CatalogVariantsMetafieldsPostRequestBodyContentApplicationJsonSchemaItems:
      type: object
      properties:
        key:
          type: string
          description: |
            The name of the field, for example: `location_id`, `color`.
        value:
          type: string
          description: |
            The value of the field, for example: `1`, `blue`.
        namespace:
          type: string
          description: |
            Namespace for the metafield, for organizational purposes.
        permission_set:
          $ref: '#/components/schemas/CatalogVariantsMetafieldsPostRequestBodyContentApplicationJsonSchemaItemsPermissionSet'
          description: >
            Determines the visibility and writeability of the field by other API consumers.

            | Value | Description |

            | :--- | :--- |

            | `app_only` | Private to the app that owns the field. |

            | `read` | Visible to other API consumers. |

            | `write` | Open for reading and writing by other API consumers. |

            | `read_and_sf_access` | Visible to other API consumers, including on the storefront. |

            | `write_and_sf_access` | Open for reading and writing by other API consumers, including on the storefront.
            |
        description:
          type: string
          description: |
            Description for the metafields.
        resource_id:
          type: integer
          description: |
            The ID for the product variant with which the metafield is associated.
      required:
        - key
        - value
        - namespace
        - permission_set
        - resource_id
      description: |
        Common metafield properties.
      title: CatalogVariantsMetafieldsPostRequestBodyContentApplicationJsonSchemaItems
    MetaFieldCollectionResponse_POST_PUT:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Metafield'
        errors:
          type: array
          items:
            description: Any type
          description: Empty for 200 responses.
        meta:
          $ref: '#/components/schemas/CollectionMeta'
      description: |
        Response payload for the BigCommerce API.
      title: MetaFieldCollectionResponse_POST_PUT
    CreateVariantsMetafieldsRequestBadRequestError:
      type: object
      properties:
        status:
          type: number
          format: double
        title:
          type: string
        type:
          type: string
        detail:
          type: string
      title: CreateVariantsMetafieldsRequestBadRequestError
    ErrorDetail:
      type: object
      properties: {}
      description: |
        Error detail response payload for the BigCommerce API.
      title: ErrorDetail
    Error:
      type: object
      properties:
        status:
          type: integer
          description: |
            The HTTP status code for the error.
        title:
          type: string
          description: |
            The error title.
        type:
          type: string
          description: |
            The error type.
        errors:
          $ref: '#/components/schemas/ErrorDetail'
      description: |
        Error response payload for the BigCommerce API.
      title: Error
    WriteCollectionPartialSuccessMeta:
      type: object
      properties:
        total:
          type: integer
          description: |
            Total number of items in the result set.
        success:
          type: integer
          description: |
            Total number of items that were successfully deleted.
        failed:
          type: integer
          description: |
            Total number of items that failed to be deleted.
      description: Additional data about the response.
      title: WriteCollectionPartialSuccessMeta
    MetaFieldCollectionResponsePartialSuccess_POST_PUT:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Metafield'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
        meta:
          $ref: '#/components/schemas/WriteCollectionPartialSuccessMeta'
      description: |
        Response payload for the BigCommerce API.
      title: MetaFieldCollectionResponsePartialSuccess_POST_PUT
    CatalogVariantsMetafieldsPutRequestBodyContentApplicationJsonSchemaItemsPermissionSet:
      type: string
      enum:
        - app_only
        - read
        - write
        - read_and_sf_access
        - write_and_sf_access
      description: |
        Determines the visibility and writeability of the field by other API consumers.
        | Value | Description |
        | :--- | :--- |
        | `app_only` | Private to the app that owns the field. |
        | `read` | Visible to other API consumers. |
        | `write` | Open for reading and writing by other API consumers. |
        | `read_and_sf_access` | Visible to other API consumers, including on the storefront. |
        | `write_and_sf_access` | Open for reading and writing by other API consumers, including on the storefront. |
      title: CatalogVariantsMetafieldsPutRequestBodyContentApplicationJsonSchemaItemsPermissionSet
    CatalogVariantsMetafieldsPutRequestBodyContentApplicationJsonSchemaItems:
      type: object
      properties:
        key:
          type: string
          description: |
            The name of the field, for example: `location_id`, `color`.
        value:
          type: string
          description: |
            The value of the field, for example: `1`, `blue`.
        namespace:
          type: string
          description: |
            Namespace for the metafield, for organizational purposes.
        permission_set:
          $ref: '#/components/schemas/CatalogVariantsMetafieldsPutRequestBodyContentApplicationJsonSchemaItemsPermissionSet'
          description: >
            Determines the visibility and writeability of the field by other API consumers.

            | Value | Description |

            | :--- | :--- |

            | `app_only` | Private to the app that owns the field. |

            | `read` | Visible to other API consumers. |

            | `write` | Open for reading and writing by other API consumers. |

            | `read_and_sf_access` | Visible to other API consumers, including on the storefront. |

            | `write_and_sf_access` | Open for reading and writing by other API consumers, including on the storefront.
            |
        description:
          type: string
          description: |
            Description for the metafields.
        id:
          type: integer
          description: |
            The ID of metafield to update.
      required:
        - id
      description: |
        Common Metafield properties.
      title: CatalogVariantsMetafieldsPutRequestBodyContentApplicationJsonSchemaItems
    UpdateVariantsMetafieldsRequestBadRequestError:
      type: object
      properties:
        status:
          type: number
          format: double
        title:
          type: string
        type:
          type: string
        detail:
          type: string
      title: UpdateVariantsMetafieldsRequestBadRequestError
    WriteCollectionSuccessMeta:
      type: object
      properties:
        total:
          type: integer
          description: |
            Total number of items in the result set.
        success:
          type: integer
          description: |
            Total number of items that were successfully deleted.
        failed:
          type: integer
          description: |
            Total number of items that failed to be deleted.
      description: Additional data about the response.
      title: WriteCollectionSuccessMeta
    MetaFieldCollectionDeleteResponseSuccess:
      type: object
      properties:
        data:
          type: array
          items:
            type: integer
        errors:
          type: array
          items:
            description: Any type
          description: Empty for 200 responses.
        meta:
          $ref: '#/components/schemas/WriteCollectionSuccessMeta'
      description: |
        Response payload for the BigCommerce API.
      title: MetaFieldCollectionDeleteResponseSuccess
    DeleteVariantsMetafieldsRequestBadRequestError:
      type: object
      properties:
        status:
          type: number
          format: double
        title:
          type: string
        type:
          type: string
        detail:
          type: string
      title: DeleteVariantsMetafieldsRequestBadRequestError
    MetaFieldCollectionResponsePartialSuccess_DELETE:
      type: object
      properties:
        data:
          type: array
          items:
            type: integer
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
        meta:
          $ref: '#/components/schemas/WriteCollectionPartialSuccessMeta'
      description: |
        Response payload for the BigCommerce API.
      title: MetaFieldCollectionResponsePartialSuccess_DELETE
    CatalogProductsProductIdVariantsVariantIdImagePostResponsesContentApplicationJsonSchemaData:
      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.
      title: CatalogProductsProductIdVariantsVariantIdImagePostResponsesContentApplicationJsonSchemaData
    Images_createProductVariantImage_Response_200:
      type: object
      properties:
        data:
          $ref: >-
            #/components/schemas/CatalogProductsProductIdVariantsVariantIdImagePostResponsesContentApplicationJsonSchemaData
          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
      title: Images_createProductVariantImage_Response_200
    CreateProductVariantImageRequestBadRequestError:
      type: object
      properties: {}
      title: CreateProductVariantImageRequestBadRequestError
    CreateProductVariantImageRequestNotFoundError:
      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.
      title: CreateProductVariantImageRequestNotFoundError
    CatalogProductsProductIdVariantsVariantIdImagePostResponsesContentApplicationJsonSchemaErrors:
      type: object
      properties: {}
      title: CatalogProductsProductIdVariantsVariantIdImagePostResponsesContentApplicationJsonSchemaErrors
    CreateProductVariantImageRequestUnprocessableEntityError:
      type: object
      properties:
        errors:
          $ref: >-
            #/components/schemas/CatalogProductsProductIdVariantsVariantIdImagePostResponsesContentApplicationJsonSchemaErrors
        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
      title: CreateProductVariantImageRequestUnprocessableEntityError
    CreateProductVariantImageRequestInternalServerError:
      type: object
      properties:
        errors:
          $ref: >-
            #/components/schemas/CatalogProductsProductIdVariantsVariantIdImagePostResponsesContentApplicationJsonSchemaErrors
        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
      title: CreateProductVariantImageRequestInternalServerError
    MetafieldBasePermissionSet:
      type: string
      enum:
        - app_only
        - read
        - write
        - read_and_sf_access
        - write_and_sf_access
      description: |-
        Determines the visibility and writeability of the field by other API consumers.

        |Value|Description
        |-|-|
        |`app_only`|Private to the app that owns the field|
        |`read`|Visible to other API consumers|
        |`write`|Open for reading and writing by other API consumers|
        |`read_and_sf_access`|Visible to other API consumers, including on storefront|
        |`write_and_sf_access`|Open for reading and writing by other API consumers, including on storefront|
      title: MetafieldBasePermissionSet
    MetafieldFullResourceType:
      type: string
      enum:
        - category
        - brand
        - product
        - variant
      description: |
        The type of resource with which the metafield is associated.
      title: MetafieldFullResourceType
    metafield_Full:
      type: object
      properties:
        key:
          type: string
          description: |
            The name of the field, for example: `location_id`, `color`. Required for POST.
        value:
          type: string
          description: >
            The value of the field, for example: `1`, `blue`. You must enter a JSON formatted string for
            [ShipperHQ](/developer/docs/admin/store-configuration/shipping/shipper-hq#shipperhq-object-properties)
            metafields. Required for POST.
        namespace:
          type: string
          description: |
            Namespace for the metafield, for organizational purposes. This is set by the developer. Required for POST.
        permission_set:
          $ref: '#/components/schemas/MetafieldBasePermissionSet'
          description: |-
            Determines the visibility and writeability of the field by other API consumers.

            |Value|Description
            |-|-|
            |`app_only`|Private to the app that owns the field|
            |`read`|Visible to other API consumers|
            |`write`|Open for reading and writing by other API consumers|
            |`read_and_sf_access`|Visible to other API consumers, including on storefront|
            |`write_and_sf_access`|Open for reading and writing by other API consumers, including on storefront|
        description:
          type: string
          description: |
            Description for the metafields.
        id:
          type: integer
          description: Unique ID of the *Metafield*. Read-Only.
        resource_type:
          $ref: '#/components/schemas/MetafieldFullResourceType'
          description: |
            The type of resource with which the metafield is associated.
        resource_id:
          type: integer
          description: |
            The ID of the resource with which the metafield is associated.
        date_created:
          type: string
          format: date-time
          description: |
            Date and time of the metafieldʼs creation. Read-Only.
        date_modified:
          type: string
          format: date-time
          description: |
            Date and time when the metafield was last updated. Read-Only.
      required:
        - key
        - value
        - namespace
        - permission_set
      title: metafield_Full
    categoriesTreeNode_Full:
      type: object
      properties:
        id:
          type: integer
          description: |
            The unique numeric ID of the category; increments sequentially.
        parent_id:
          type: integer
          description: >
            The unique numeric ID of the categoryʼs parent. This field controls where the category sits in the tree of
            categories that organize the catalog.
        name:
          type: string
          description: |
            The name displayed for the category. Name is unique with respect to the categoryʼs siblings.
        is_visible:
          type: boolean
          description: >
            Flag to determine whether the product should be displayed to customers browsing the store. If `true`, the
            category will be displayed. If `false`, the category will be hidden from view.
        url:
          type: string
          description: |
            The custom URL for the category on the storefront.
      description: Used to reflect parent <> child category relationships. Used by Category Tree.
      title: categoriesTreeNode_Full
    categoriesTree_Resp:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/categoriesTreeNode_Full'
        meta:
          $ref: '#/components/schemas/metaEmpty_Full'
      description: >
        Returns the categories tree, a nested lineage of the categories with parent->child relationship. The Category
        objects returned are simplified versions of the category objects returned in the rest of this API.
      title: categoriesTree_Resp
    Metafields_getProductVariantMetafields_Response_200:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/metafield_Full'
        meta:
          $ref: '#/components/schemas/categoriesTree_Resp'
      title: Metafields_getProductVariantMetafields_Response_200
    metafield_Base:
      type: object
      properties:
        key:
          type: string
          description: |
            The name of the field, for example: `location_id`, `color`. Required for POST.
        value:
          type: string
          description: >
            The value of the field, for example: `1`, `blue`. You must enter a JSON formatted string for
            [ShipperHQ](/developer/docs/admin/store-configuration/shipping/shipper-hq#shipperhq-object-properties)
            metafields. Required for POST.
        namespace:
          type: string
          description: |
            Namespace for the metafield, for organizational purposes. This is set by the developer. Required for POST.
        permission_set:
          $ref: '#/components/schemas/MetafieldBasePermissionSet'
          description: |-
            Determines the visibility and writeability of the field by other API consumers.

            |Value|Description
            |-|-|
            |`app_only`|Private to the app that owns the field|
            |`read`|Visible to other API consumers|
            |`write`|Open for reading and writing by other API consumers|
            |`read_and_sf_access`|Visible to other API consumers, including on storefront|
            |`write_and_sf_access`|Open for reading and writing by other API consumers, including on storefront|
        description:
          type: string
          description: |
            Description for the metafields.
      required:
        - key
        - value
        - namespace
        - permission_set
      description: >-
        Metafield for products, categories, variants, and brands; the max number of metafields allowed on each is 50.
        For more information, see [Platform Limits](https://support.bigcommerce.com/s/article/Platform-Limits) in the
        Help Center.
      title: metafield_Base
    Metafields_createProductVariantMetafield_Response_200:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/metafield_Full'
        meta:
          $ref: '#/components/schemas/metaEmpty_Full'
      title: Metafields_createProductVariantMetafield_Response_200
    CreateProductVariantMetafieldRequestBadRequestError:
      type: object
      properties:
        status:
          type: number
          format: double
        title:
          type: string
        type:
          type: string
        detail:
          type: string
      title: CreateProductVariantMetafieldRequestBadRequestError
    CatalogProductsProductIdVariantsVariantIdMetafieldsPostResponsesContentApplicationJsonSchemaErrors:
      type: object
      properties: {}
      title: CatalogProductsProductIdVariantsVariantIdMetafieldsPostResponsesContentApplicationJsonSchemaErrors
    CreateProductVariantMetafieldRequestConflictError:
      type: object
      properties:
        errors:
          $ref: >-
            #/components/schemas/CatalogProductsProductIdVariantsVariantIdMetafieldsPostResponsesContentApplicationJsonSchemaErrors
        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
      title: CreateProductVariantMetafieldRequestConflictError
    CreateProductVariantMetafieldRequestUnprocessableEntityError:
      type: object
      properties:
        errors:
          $ref: >-
            #/components/schemas/CatalogProductsProductIdVariantsVariantIdMetafieldsPostResponsesContentApplicationJsonSchemaErrors
        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
      title: CreateProductVariantMetafieldRequestUnprocessableEntityError
    Metafields_getProductVariantMetafield_Response_200:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/metafield_Full'
        meta:
          $ref: '#/components/schemas/metaEmpty_Full'
      title: Metafields_getProductVariantMetafield_Response_200
    GetProductVariantMetafieldRequestNotFoundError:
      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.
      title: GetProductVariantMetafieldRequestNotFoundError
    Metafields_updateProductVariantMetafield_Response_200:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/metafield_Full'
        meta:
          $ref: '#/components/schemas/metaEmpty_Full'
      title: Metafields_updateProductVariantMetafield_Response_200
    UpdateProductVariantMetafieldRequestBadRequestError:
      type: object
      properties:
        status:
          type: number
          format: double
        title:
          type: string
        type:
          type: string
        detail:
          type: string
      title: UpdateProductVariantMetafieldRequestBadRequestError
    UpdateProductVariantMetafieldRequestNotFoundError:
      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.
      title: UpdateProductVariantMetafieldRequestNotFoundError
    DeleteProductVariantMetafieldRequestNotFoundError:
      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.
      title: DeleteProductVariantMetafieldRequestNotFoundError
    CatalogVariantsGetResponsesContentApplicationJsonSchemaDataItemsOptionValuesItems:
      type: object
      properties:
        option_display_name:
          type: string
          description: |
            The name of the option.
        label:
          type: string
          description: |
            The label of the option value.
        id:
          type: integer
        option_id:
          type: integer
      description: Common Option Value Product properties.
      title: CatalogVariantsGetResponsesContentApplicationJsonSchemaDataItemsOptionValuesItems
    CatalogVariantsGetResponsesContentApplicationJsonSchemaDataItems:
      type: object
      properties:
        cost_price:
          type: number
          format: double
          description: >-
            The cost price of the variant. It is not affected by Price List prices. This value displays as null in the
            control panel when `cost_price` equals zero.
        price:
          type: number
          format: double
          description: >-
            This variant’s base price on the storefront. If a Price List ID is used, the Price List value will be used.
            If a Price List ID is not used, and this value is `null`, the product’s default price (set in the Product
            resource’s `price` field) will be used as the base price.
        sale_price:
          type: number
          format: double
          description: >-
            This variant’s sale price on the storefront. If a Price List ID is used, the Price List value will be used.
            If a Price List ID is not used, and this value is null, the product’s sale price (set in the Product
            resource’s `price` field) will be used as the sale price.
        retail_price:
          type: number
          format: double
          description: >-
            This variant’s retail price on the storefront. If a Price List ID is used, the Price List value will be
            used. If a Price List ID is not used, and this value is null, the product’s retail price (set in the Product
            resource’s `price` field) will be used as the retail price.
        weight:
          type: number
          format: double
          description: >-
            This variant’s base weight on the storefront. If this value is null, the product’s default weight (set in
            the Product resource’s weight field) will be used as the base weight.
        width:
          type: number
          format: double
          description: >
            Width of the variant, which can be used when calculating shipping costs. If this value is `null`, the
            productʼs default width (set in the Product resourceʼs `width` field) will be used as the base width.
        height:
          type: number
          format: double
          description: >
            Height of the variant, which can be used when calculating shipping costs. If this value is `null`, the
            productʼs default height (set in the Product resourceʼs `height` field) will be used as the base height.
        depth:
          type: number
          format: double
          description: >
            Depth of the variant, which can be used when calculating shipping costs. If this value is `null`, the
            productʼs default depth (set in the Product resourceʼs `depth` field) will be used as the base depth.
        is_free_shipping:
          type: boolean
          description: >
            Flag used to indicate whether the variant has free shipping. If `true`, the shipping cost for the variant
            will be zero.
        fixed_cost_shipping_price:
          type: number
          format: double
          description: >
            A fixed shipping cost for the variant. If defined, this value will be used during checkout instead of normal
            shipping-cost calculation.
        purchasing_disabled:
          type: boolean
          description: If `true`, this variant will not be purchasable on the storefront.
        purchasing_disabled_message:
          type: string
          description: If `purchasing_disabled` is `true`, this message should show on the storefront when the variant is selected.
        upc:
          type:
            - string
            - 'null'
          description: The UPC code used in feeds for shopping comparison sites and external channel integrations.
        inventory_level:
          type: integer
          description: >-
            Inventory level for the variant, which is used when the product’s inventory_tracking is set to `variant`.
            The Catalog API returns the inventory for only the default location.


            The inventory for a variant cannot exceed 2,147,483,647 in the catalog. The sum of the variant inventories,
            or the total inventory for a product, cannot exceed 2,147,483,647. 


            If you exceed the limit, the store sets the variant inventory to the limit if no other variant inventories
            are set. If other variant inventories are set, the store does not save the variant inventory rather than
            setting the variant inventory to the remaining limit.


            The Catalog API handles limits in a different way than the Inventory API. For more information, see [Limit
            handling](/developer/docs/admin/catalog-and-inventory/inventory-adjustments#limit-handling-in-inventory-versus-catalog-api). 
        inventory_warning_level:
          type: integer
          description: When the variant hits this inventory level, it is considered low stock.
        bin_picking_number:
          type: string
          description: Identifies where in a warehouse the variant is located.
        id:
          type: integer
        product_id:
          type: integer
        sku:
          type: string
        sku_id:
          type: integer
          description: Read-only reference to v2 APIʼs SKU ID. Null if it is a base variant.
        option_values:
          type: array
          items:
            $ref: '#/components/schemas/CatalogVariantsGetResponsesContentApplicationJsonSchemaDataItemsOptionValuesItems'
          description: >-
            Array of option and option values IDs that make up this variant. Will be empty if the variant is the
            productʼs base variant.
        calculated_price:
          type: number
          format: double
          description: >
            The price of the variant as seen on the storefront. This price takes into account `sale_price` and any price
            adjustment rules that are applicable to this variant.
      description: Common Variant properties.
      title: CatalogVariantsGetResponsesContentApplicationJsonSchemaDataItems
    Variants (Batch)_getVariants_Response_200:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/CatalogVariantsGetResponsesContentApplicationJsonSchemaDataItems'
        meta:
          $ref: '#/components/schemas/metaCollection_Full'
      title: Variants (Batch)_getVariants_Response_200
    GetVariantsRequestNotFoundError:
      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.
      title: GetVariantsRequestNotFoundError
    CatalogVariantsPutRequestBodyContentApplicationJsonSchemaItems:
      type: object
      properties:
        cost_price:
          type: number
          format: double
          description: >-
            The cost price of the variant. It is not affected by Price List prices. This value displays as null in the
            control panel when `cost_price` equals zero.
        price:
          type: number
          format: double
          description: >-
            This variant’s base price on the storefront. If a Price List ID is used, the Price List value will be used.
            If a Price List ID is not used, and this value is `null`, the product’s default price (set in the Product
            resource’s `price` field) will be used as the base price.
        sale_price:
          type: number
          format: double
          description: >-
            This variant’s sale price on the storefront. If a Price List ID is used, the Price List value will be used.
            If a Price List ID is not used, and this value is null, the product’s sale price (set in the Product
            resource’s `price` field) will be used as the sale price.
        retail_price:
          type: number
          format: double
          description: >-
            This variant’s retail price on the storefront. If a Price List ID is used, the Price List value will be
            used. If a Price List ID is not used, and this value is null, the product’s retail price (set in the Product
            resource’s `price` field) will be used as the retail price.
        weight:
          type: number
          format: double
          description: >-
            This variant’s base weight on the storefront. If this value is null, the product’s default weight (set in
            the Product resource’s weight field) will be used as the base weight.
        width:
          type: number
          format: double
          description: >
            Width of the variant, which can be used when calculating shipping costs. If this value is `null`, the
            productʼs default width (set in the Product resourceʼs `width` field) will be used as the base width.
        height:
          type: number
          format: double
          description: >
            Height of the variant, which can be used when calculating shipping costs. If this value is `null`, the
            productʼs default height (set in the Product resourceʼs `height` field) will be used as the base height.
        depth:
          type: number
          format: double
          description: >
            Depth of the variant, which can be used when calculating shipping costs. If this value is `null`, the
            productʼs default depth (set in the Product resourceʼs `depth` field) will be used as the base depth.
        is_free_shipping:
          type: boolean
          description: >
            Flag used to indicate whether the variant has free shipping. If `true`, the shipping cost for the variant
            will be zero.
        fixed_cost_shipping_price:
          type: number
          format: double
          description: >
            A fixed shipping cost for the variant. If defined, this value will be used during checkout instead of normal
            shipping-cost calculation.
        purchasing_disabled:
          type: boolean
          description: If `true`, this variant will not be purchasable on the storefront.
        purchasing_disabled_message:
          type: string
          description: If `purchasing_disabled` is `true`, this message should show on the storefront when the variant is selected.
        upc:
          type:
            - string
            - 'null'
          description: The UPC code used in feeds for shopping comparison sites and external channel integrations.
        inventory_level:
          type: integer
          description: >-
            Inventory level for the variant, which is used when the product’s inventory_tracking is set to `variant`.
            The Catalog API returns the inventory for only the default location.


            The inventory for a variant cannot exceed 2,147,483,647 in the catalog. The sum of the variant inventories,
            or the total inventory for a product, cannot exceed 2,147,483,647. 


            If you exceed the limit, the store sets the variant inventory to the limit if no other variant inventories
            are set. If other variant inventories are set, the store does not save the variant inventory rather than
            setting the variant inventory to the remaining limit.


            The Catalog API handles limits in a different way than the Inventory API. For more information, see [Limit
            handling](/developer/docs/admin/catalog-and-inventory/inventory-adjustments#limit-handling-in-inventory-versus-catalog-api). 
        inventory_warning_level:
          type: integer
          description: When the variant hits this inventory level, it is considered low stock.
        bin_picking_number:
          type: string
          description: Identifies where in a warehouse the variant is located.
        id:
          type: integer
      description: |
        The model for a PUT to update variants on a product.
      title: CatalogVariantsPutRequestBodyContentApplicationJsonSchemaItems
    CatalogVariantsPutResponsesContentApplicationJsonSchemaDataItemsOptionValuesItems:
      type: object
      properties:
        option_display_name:
          type: string
          description: |
            The name of the option.
        label:
          type: string
          description: |
            The label of the option value.
        id:
          type: integer
        option_id:
          type: integer
      description: Common Option Value Product properties.
      title: CatalogVariantsPutResponsesContentApplicationJsonSchemaDataItemsOptionValuesItems
    CatalogVariantsPutResponsesContentApplicationJsonSchemaDataItems:
      type: object
      properties:
        cost_price:
          type: number
          format: double
          description: >-
            The cost price of the variant. It is not affected by Price List prices. This value displays as null in the
            control panel when `cost_price` equals zero.
        price:
          type: number
          format: double
          description: >-
            This variant’s base price on the storefront. If a Price List ID is used, the Price List value will be used.
            If a Price List ID is not used, and this value is `null`, the product’s default price (set in the Product
            resource’s `price` field) will be used as the base price.
        sale_price:
          type: number
          format: double
          description: >-
            This variant’s sale price on the storefront. If a Price List ID is used, the Price List value will be used.
            If a Price List ID is not used, and this value is null, the product’s sale price (set in the Product
            resource’s `price` field) will be used as the sale price.
        retail_price:
          type: number
          format: double
          description: >-
            This variant’s retail price on the storefront. If a Price List ID is used, the Price List value will be
            used. If a Price List ID is not used, and this value is null, the product’s retail price (set in the Product
            resource’s `price` field) will be used as the retail price.
        weight:
          type: number
          format: double
          description: >-
            This variant’s base weight on the storefront. If this value is null, the product’s default weight (set in
            the Product resource’s weight field) will be used as the base weight.
        width:
          type: number
          format: double
          description: >
            Width of the variant, which can be used when calculating shipping costs. If this value is `null`, the
            productʼs default width (set in the Product resourceʼs `width` field) will be used as the base width.
        height:
          type: number
          format: double
          description: >
            Height of the variant, which can be used when calculating shipping costs. If this value is `null`, the
            productʼs default height (set in the Product resourceʼs `height` field) will be used as the base height.
        depth:
          type: number
          format: double
          description: >
            Depth of the variant, which can be used when calculating shipping costs. If this value is `null`, the
            productʼs default depth (set in the Product resourceʼs `depth` field) will be used as the base depth.
        is_free_shipping:
          type: boolean
          description: >
            Flag used to indicate whether the variant has free shipping. If `true`, the shipping cost for the variant
            will be zero.
        fixed_cost_shipping_price:
          type: number
          format: double
          description: >
            A fixed shipping cost for the variant. If defined, this value will be used during checkout instead of normal
            shipping-cost calculation.
        purchasing_disabled:
          type: boolean
          description: If `true`, this variant will not be purchasable on the storefront.
        purchasing_disabled_message:
          type: string
          description: If `purchasing_disabled` is `true`, this message should show on the storefront when the variant is selected.
        upc:
          type:
            - string
            - 'null'
          description: The UPC code used in feeds for shopping comparison sites and external channel integrations.
        inventory_level:
          type: integer
          description: >-
            Inventory level for the variant, which is used when the product’s inventory_tracking is set to `variant`.
            The Catalog API returns the inventory for only the default location.


            The inventory for a variant cannot exceed 2,147,483,647 in the catalog. The sum of the variant inventories,
            or the total inventory for a product, cannot exceed 2,147,483,647. 


            If you exceed the limit, the store sets the variant inventory to the limit if no other variant inventories
            are set. If other variant inventories are set, the store does not save the variant inventory rather than
            setting the variant inventory to the remaining limit.


            The Catalog API handles limits in a different way than the Inventory API. For more information, see [Limit
            handling](/developer/docs/admin/catalog-and-inventory/inventory-adjustments#limit-handling-in-inventory-versus-catalog-api). 
        inventory_warning_level:
          type: integer
          description: When the variant hits this inventory level, it is considered low stock.
        bin_picking_number:
          type: string
          description: Identifies where in a warehouse the variant is located.
        id:
          type: integer
        product_id:
          type: integer
        sku:
          type: string
        sku_id:
          type: integer
          description: Read-only reference to v2 APIʼs SKU ID. Null if it is a base variant.
        option_values:
          type: array
          items:
            $ref: '#/components/schemas/CatalogVariantsPutResponsesContentApplicationJsonSchemaDataItemsOptionValuesItems'
          description: >-
            Array of option and option values IDs that make up this variant. Will be empty if the variant is the
            productʼs base variant.
        calculated_price:
          type: number
          format: double
          description: >
            The price of the variant as seen on the storefront. This price takes into account `sale_price` and any price
            adjustment rules that are applicable to this variant.
      description: Common Variant properties.
      title: CatalogVariantsPutResponsesContentApplicationJsonSchemaDataItems
    CatalogVariantsPutResponsesContentApplicationJsonSchemaMetaPaginationLinks:
      type: object
      properties:
        previous:
          type: string
          description: |
            Link to the previous page returned in the response.
        current:
          type: string
          description: |
            Link to the current page returned in the response.
        next:
          type: string
          description: |
            Link to the next page returned in the response.
      description: |
        Pagination links for the previous and next parts of the whole collection.
      title: CatalogVariantsPutResponsesContentApplicationJsonSchemaMetaPaginationLinks
    CatalogVariantsPutResponsesContentApplicationJsonSchemaMetaPagination:
      type: object
      properties:
        total:
          type: integer
          description: |
            Total number of items in the result set.
        count:
          type: integer
          description: |
            Total number of items in the collection response.
        per_page:
          type: integer
          description: |
            The amount of items returned in the collection per page, controlled by the limit parameter.
        current_page:
          type: integer
          description: |
            The page you are currently on within the collection.
        total_pages:
          type: integer
          description: |
            The total number of pages in the collection.
        links:
          $ref: '#/components/schemas/CatalogVariantsPutResponsesContentApplicationJsonSchemaMetaPaginationLinks'
          description: |
            Pagination links for the previous and next parts of the whole collection.
      description: Data about the response, including pagination and collection totals.
      title: CatalogVariantsPutResponsesContentApplicationJsonSchemaMetaPagination
    CatalogVariantsPutResponsesContentApplicationJsonSchemaMeta:
      type: object
      properties:
        pagination:
          $ref: '#/components/schemas/CatalogVariantsPutResponsesContentApplicationJsonSchemaMetaPagination'
          description: Data about the response, including pagination and collection totals.
      description: Data about the response, including pagination and collection totals.
      title: CatalogVariantsPutResponsesContentApplicationJsonSchemaMeta
    Variants (Batch)_updateVariantsBatch_Response_200:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/CatalogVariantsPutResponsesContentApplicationJsonSchemaDataItems'
        meta:
          $ref: '#/components/schemas/CatalogVariantsPutResponsesContentApplicationJsonSchemaMeta'
          description: Data about the response, including pagination and collection totals.
      title: Variants (Batch)_updateVariantsBatch_Response_200
    CatalogVariantsPutResponsesContentApplicationJsonSchemaBatchErrorsItemsErrors:
      type: object
      properties: {}
      title: CatalogVariantsPutResponsesContentApplicationJsonSchemaBatchErrorsItemsErrors
    CatalogVariantsPutResponsesContentApplicationJsonSchemaBatchErrorsItems:
      type: object
      properties:
        status:
          type: integer
          description: |
            The HTTP status code.
        title:
          type: string
          description: |
            The error title describing the particular error.
        type:
          type: string
        instance:
          type: string
        errors:
          $ref: '#/components/schemas/CatalogVariantsPutResponsesContentApplicationJsonSchemaBatchErrorsItemsErrors'
      description: |
        Error payload for the BigCommerce API.
      title: CatalogVariantsPutResponsesContentApplicationJsonSchemaBatchErrorsItems
    UpdateVariantsBatchRequestUnprocessableEntityError:
      type: object
      properties:
        batch_errors:
          type: array
          items:
            $ref: '#/components/schemas/CatalogVariantsPutResponsesContentApplicationJsonSchemaBatchErrorsItems'
      description: |
        Errors during batch usage for the BigCommerce API.
      title: UpdateVariantsBatchRequestUnprocessableEntityError
  securitySchemes:
    X-Auth-Token:
      type: apiKey
      in: header
      name: X-Auth-Token
      description: >-
        ### OAuth scopes


        | UI Name | Permission | Parameter |

        |:--------|:-----------|:----------|

        |  Products | modify | `store_v2_products` |

        |  Products | read-only | `store_v2_products_read_only` |


        ### Authentication header


        | Header | Argument | Description |

        |:-------|:---------|:------------|

        | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to
        API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


        ### Further reading


        For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example
        Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests).


        For more about BigCommerce OAuth scopes, see our [Guide to API
        Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes).


        For a list of API status codes, see [API Status
        Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
