openapi: 3.1.0
info:
  title: 'Admin Management: Pricing'
  version: 1.0.0
paths:
  /stores/{store_hash}/v3/pricing/products:
    post:
      operationId: getPrices
      summary: Get Prices (batch)
      description: >-
        Calculate batch pricing for products for a specific channel, currency, and customer group.


        The rounded prices in this endpoint's response will align with the currency's decimal precision as defined in
        the [currency](https://support.bigcommerce.com/s/article/Managing-Currencies?language=en_US#add) settings page.


        **Limits**

        * Limit of 50 concurrent requests.
      tags:
        - products
      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 | 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
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Products_getPrices_Response_200'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                channel_id:
                  type: integer
                  description: The channel ID that pricing evaluates within. The default BigCommerce storefront is channel 1.
                currency_code:
                  type: string
                  description: The currency code of prices this request returns.
                country_code:
                  type: string
                  description: An ISO 3166-1 alpha-2 shopper's country code representing a country or special geographic area.
                customer_group_id:
                  type: integer
                  description: The customer group ID that's relevant for any customer group pricing, tax values, etc.
                customer_id:
                  type: integer
                  description: The ID of the customer for whom to fetch prices.
                items:
                  type: array
                  items:
                    $ref: '#/components/schemas/PricingProductsPostRequestBodyContentApplicationJsonSchemaItemsItems'
                  description: The items for which to fetch prices.
              required:
                - channel_id
                - currency_code
                - items
servers:
  - url: https://api.bigcommerce.com
    description: https://api.bigcommerce.com
components:
  schemas:
    PricingProductsPostRequestBodyContentApplicationJsonSchemaItemsItemsOptionsItems:
      type: object
      properties:
        option_id:
          type: integer
          description: The ID of the variant option or modifier option that is being configured for this product.
        value_id:
          type: integer
          description: |-
            The ID of the value matching the option that's being configured. 

            **Note:*** This must be the ID, not the value.
      title: PricingProductsPostRequestBodyContentApplicationJsonSchemaItemsItemsOptionsItems
    PricingProductsPostRequestBodyContentApplicationJsonSchemaItemsItems:
      type: object
      properties:
        product_id:
          type: integer
          description: The (required) product ID of the item.
        variant_id:
          type: number
          format: double
          description: The (optional) variant ID of the item.
        options:
          type: array
          items:
            $ref: '#/components/schemas/PricingProductsPostRequestBodyContentApplicationJsonSchemaItemsItemsOptionsItems'
          description: The option configuration of the product (optional); might be partially configured for estimates.
      description: Details/configuration for the product to request a price for.
      title: PricingProductsPostRequestBodyContentApplicationJsonSchemaItemsItems
    PricingProductsPostResponsesContentApplicationJsonSchemaDataItemsOptionsItems:
      type: object
      properties:
        option_id:
          type: integer
          description: The ID of the variant option or modifier option configured for this price.
        value_id:
          type: integer
          description: The selected value ID for the configured option.
      title: PricingProductsPostResponsesContentApplicationJsonSchemaDataItemsOptionsItems
    ReferenceRequestOptionsItems:
      type: object
      properties:
        option_id:
          type: integer
          description: The ID of the variant option or modifier option configured for this price.
        value_id:
          type: integer
          description: The selected value ID for the configured option.
      title: ReferenceRequestOptionsItems
    ReferenceRequest:
      type: object
      properties:
        product_id:
          type: integer
          description: The (required) product ID of the item.
        variant_id:
          type: integer
          description: The (optional) variant ID of the item.
        options:
          type: array
          items:
            $ref: '#/components/schemas/ReferenceRequestOptionsItems'
          description: The optional product option configuration for this generated price.
      description: You can use the original details of the request to identify the exact product variant and fetch prices.
      title: ReferenceRequest
    PricingProductsPostResponsesContentApplicationJsonSchemaDataItemsRetailPrice:
      type: object
      properties:
        as_entered:
          type: number
          format: double
          description: The price provided by the merchant, as entered in their catalog/price list; may include or exclude tax.
        entered_inclusive:
          type: boolean
          description: >-
            Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the store's tax
            jurisdiction.
        tax_exclusive:
          type: number
          format: double
          description: The estimated tax-exclusive price for this product based on the provided customer group.
        tax_inclusive:
          type: number
          format: double
          description: The estimated tax-inclusive price for this product based on the provided customer group.
      description: >-
        The (optional) RRP/retail price configured for this product and used for price comparison and storefront display
        purposes.
      title: PricingProductsPostResponsesContentApplicationJsonSchemaDataItemsRetailPrice
    PricingProductsPostResponsesContentApplicationJsonSchemaDataItemsSalePrice:
      type: object
      properties:
        as_entered:
          type: number
          format: double
          description: The price provided by the merchant, as entered in their catalog/price list; may include or exclude tax.
        entered_inclusive:
          type: boolean
          description: >-
            Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the store's tax
            jurisdiction.
        tax_exclusive:
          type: number
          format: double
          description: The estimated tax-exclusive price for this product based on the provided customer group.
        tax_inclusive:
          type: number
          format: double
          description: The estimated tax-inclusive price for this product based on the provided customer group.
      description: The merchant-entered sale price for a product overwrites the default price. The `sale_price` is optional.
      title: PricingProductsPostResponsesContentApplicationJsonSchemaDataItemsSalePrice
    PricingProductsPostResponsesContentApplicationJsonSchemaDataItemsMinimumAdvertisedPrice:
      type: object
      properties:
        as_entered:
          type: number
          format: double
          description: The price provided by the merchant, as entered in their catalog/price list; may include or exclude tax.
        entered_inclusive:
          type: boolean
          description: >-
            Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the store's tax
            jurisdiction.
        tax_exclusive:
          type: number
          format: double
          description: The estimated tax-exclusive price for this product based on the provided customer group.
        tax_inclusive:
          type: number
          format: double
          description: The estimated tax-inclusive price for this product based on the provided customer group.
      description: >-
        The minimum advertised price (MAP) you can display on a storefront. A value supplied by the merchant and used
        for display purposes.
      title: PricingProductsPostResponsesContentApplicationJsonSchemaDataItemsMinimumAdvertisedPrice
    PricingProductsPostResponsesContentApplicationJsonSchemaDataItemsSaved:
      type: object
      properties:
        as_entered:
          type: number
          format: double
          description: The price provided by the merchant, as entered in their catalog/price list; may include or exclude tax.
        entered_inclusive:
          type: boolean
          description: >-
            Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the store's tax
            jurisdiction.
        tax_exclusive:
          type: number
          format: double
          description: The estimated tax-exclusive price for this product based on the provided customer group.
        tax_inclusive:
          type: number
          format: double
          description: The estimated tax-inclusive price for this product based on the provided customer group.
      description: The amount that merchants save, determined by the difference between `retail_price` and `calculated_price`.
      title: PricingProductsPostResponsesContentApplicationJsonSchemaDataItemsSaved
    PricingProductsPostResponsesContentApplicationJsonSchemaDataItemsPrice:
      type: object
      properties:
        as_entered:
          type: number
          format: double
          description: The price provided by the merchant, as entered in their catalog/price list; may include or exclude tax.
        entered_inclusive:
          type: boolean
          description: >-
            Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the store's tax
            jurisdiction.
        tax_exclusive:
          type: number
          format: double
          description: The estimated tax-exclusive price for this product based on the provided customer group.
        tax_inclusive:
          type: number
          format: double
          description: The estimated tax-inclusive price for this product based on the provided customer group.
      description: >-
        The merchant-entered price for a product, which could include or exclude tax. When creating a product, you must
        define the price, which serves as the default price.
      title: PricingProductsPostResponsesContentApplicationJsonSchemaDataItemsPrice
    PricingProductsPostResponsesContentApplicationJsonSchemaDataItemsCalculatedPrice:
      type: object
      properties:
        as_entered:
          type: number
          format: double
          description: The price provided by the merchant, as entered in their catalog/price list; may include or exclude tax.
        entered_inclusive:
          type: boolean
          description: >-
            Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the store's tax
            jurisdiction.
        tax_exclusive:
          type: number
          format: double
          description: The estimated tax-exclusive price for this product based on the provided customer group.
        tax_inclusive:
          type: number
          format: double
          description: The estimated tax-inclusive price for this product based on the provided customer group.
      description: >-
        The shopper price for a product, which includes modifier, option, and option set rules. The `calculated_price`
        may include or exclude estimates for tax.
      title: PricingProductsPostResponsesContentApplicationJsonSchemaDataItemsCalculatedPrice
    PricingProductsPostResponsesContentApplicationJsonSchemaDataItemsPriceRangeMinimum:
      type: object
      properties:
        as_entered:
          type: number
          format: double
          description: The price provided by the merchant, as entered in their catalog/price list; may include or exclude tax.
        entered_inclusive:
          type: boolean
          description: >-
            Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the store's tax
            jurisdiction.
        tax_exclusive:
          type: number
          format: double
          description: The estimated tax-exclusive price for this product based on the provided customer group.
        tax_inclusive:
          type: number
          format: double
          description: The estimated tax-inclusive price for this product based on the provided customer group.
      description: The price for a product, including estimates for tax.
      title: PricingProductsPostResponsesContentApplicationJsonSchemaDataItemsPriceRangeMinimum
    PricingProductsPostResponsesContentApplicationJsonSchemaDataItemsPriceRangeMaximum:
      type: object
      properties:
        as_entered:
          type: number
          format: double
          description: The price provided by the merchant, as entered in their catalog/price list; may include or exclude tax.
        entered_inclusive:
          type: boolean
          description: >-
            Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the store's tax
            jurisdiction.
        tax_exclusive:
          type: number
          format: double
          description: The estimated tax-exclusive price for this product based on the provided customer group.
        tax_inclusive:
          type: number
          format: double
          description: The estimated tax-inclusive price for this product based on the provided customer group.
      description: The price for a product, including estimates for tax.
      title: PricingProductsPostResponsesContentApplicationJsonSchemaDataItemsPriceRangeMaximum
    PricingProductsPostResponsesContentApplicationJsonSchemaDataItemsPriceRange:
      type: object
      properties:
        minimum:
          $ref: '#/components/schemas/PricingProductsPostResponsesContentApplicationJsonSchemaDataItemsPriceRangeMinimum'
          description: The price for a product, including estimates for tax.
        maximum:
          $ref: '#/components/schemas/PricingProductsPostResponsesContentApplicationJsonSchemaDataItemsPriceRangeMaximum'
          description: The price for a product, including estimates for tax.
      description: >-
        The minimum and maximum price that will typically apply to this product. Only used for complex products
        (products with variants).
      title: PricingProductsPostResponsesContentApplicationJsonSchemaDataItemsPriceRange
    PricingProductsPostResponsesContentApplicationJsonSchemaDataItemsRetailPriceRangeMinimum:
      type: object
      properties:
        as_entered:
          type: number
          format: double
          description: The price provided by the merchant, as entered in their catalog/price list; may include or exclude tax.
        entered_inclusive:
          type: boolean
          description: >-
            Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the store's tax
            jurisdiction.
        tax_exclusive:
          type: number
          format: double
          description: The estimated tax-exclusive price for this product based on the provided customer group.
        tax_inclusive:
          type: number
          format: double
          description: The estimated tax-inclusive price for this product based on the provided customer group.
      description: The price for a product, including estimates for tax.
      title: PricingProductsPostResponsesContentApplicationJsonSchemaDataItemsRetailPriceRangeMinimum
    PricingProductsPostResponsesContentApplicationJsonSchemaDataItemsRetailPriceRangeMaximum:
      type: object
      properties:
        as_entered:
          type: number
          format: double
          description: The price provided by the merchant, as entered in their catalog/price list; may include or exclude tax.
        entered_inclusive:
          type: boolean
          description: >-
            Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the store's tax
            jurisdiction.
        tax_exclusive:
          type: number
          format: double
          description: The estimated tax-exclusive price for this product based on the provided customer group.
        tax_inclusive:
          type: number
          format: double
          description: The estimated tax-inclusive price for this product based on the provided customer group.
      description: The price for a product, including estimates for tax.
      title: PricingProductsPostResponsesContentApplicationJsonSchemaDataItemsRetailPriceRangeMaximum
    PricingProductsPostResponsesContentApplicationJsonSchemaDataItemsRetailPriceRange:
      type: object
      properties:
        minimum:
          $ref: >-
            #/components/schemas/PricingProductsPostResponsesContentApplicationJsonSchemaDataItemsRetailPriceRangeMinimum
          description: The price for a product, including estimates for tax.
        maximum:
          $ref: >-
            #/components/schemas/PricingProductsPostResponsesContentApplicationJsonSchemaDataItemsRetailPriceRangeMaximum
          description: The price for a product, including estimates for tax.
      description: The productʼs variants that will typically apply to this product.
      title: PricingProductsPostResponsesContentApplicationJsonSchemaDataItemsRetailPriceRange
    BulkPricingTierDiscountType:
      type: string
      enum:
        - price
        - percent
        - fixed
      title: BulkPricingTierDiscountType
    BulkPricingTierTaxDiscountAmountItems:
      type: object
      properties:
        as_entered:
          type: number
          format: double
          description: The price provided by the merchant, as entered in their catalog/price list; may include or exclude tax.
        tax_inclusive:
          type: number
          format: double
          description: The estimated tax-inclusive price for this product based on the provided customer group.
        tax_exclusive:
          type: number
          format: double
          description: The estimated tax-exclusive price for this product based on the provided customer group.
        entered_inclusive:
          type: boolean
          description: >-
            Determines whether the 'as_entered' price is inclusive or exclusive of tax based on the store's tax
            jurisdiction.
      title: BulkPricingTierTaxDiscountAmountItems
    BulkPricingTier:
      type: object
      properties:
        minimum:
          type: integer
          description: The minimum quantity required to trigger this bulk pricing discount.
        maximum:
          type: integer
          description: The maximum quantity (or 0 for unlimited) to trigger this bulk pricing discount.
        discount_amount:
          type: number
          format: double
        discount_type:
          $ref: '#/components/schemas/BulkPricingTierDiscountType'
        tax_discount_amount:
          type: array
          items:
            $ref: '#/components/schemas/BulkPricingTierTaxDiscountAmountItems'
          description: Formats the `bulk_pricing.discount_amount` into the tax price amounts.
      title: BulkPricingTier
    PricingProductsPostResponsesContentApplicationJsonSchemaDataItems:
      type: object
      properties:
        product_id:
          type: integer
          description: The (required) product ID of the item.
        variant_id:
          type: integer
          description: The (optional) variant ID of the item.
        options:
          type: array
          items:
            $ref: '#/components/schemas/PricingProductsPostResponsesContentApplicationJsonSchemaDataItemsOptionsItems'
          description: The optional product option configuration for this generated price.
        reference_request:
          $ref: '#/components/schemas/ReferenceRequest'
        retail_price:
          $ref: '#/components/schemas/PricingProductsPostResponsesContentApplicationJsonSchemaDataItemsRetailPrice'
          description: >-
            The (optional) RRP/retail price configured for this product and used for price comparison and storefront
            display purposes.
        sale_price:
          $ref: '#/components/schemas/PricingProductsPostResponsesContentApplicationJsonSchemaDataItemsSalePrice'
          description: The merchant-entered sale price for a product overwrites the default price. The `sale_price` is optional.
        minimum_advertised_price:
          $ref: '#/components/schemas/PricingProductsPostResponsesContentApplicationJsonSchemaDataItemsMinimumAdvertisedPrice'
          description: >-
            The minimum advertised price (MAP) you can display on a storefront. A value supplied by the merchant and
            used for display purposes.
        saved:
          $ref: '#/components/schemas/PricingProductsPostResponsesContentApplicationJsonSchemaDataItemsSaved'
          description: The amount that merchants save, determined by the difference between `retail_price` and `calculated_price`.
        price:
          $ref: '#/components/schemas/PricingProductsPostResponsesContentApplicationJsonSchemaDataItemsPrice'
          description: >-
            The merchant-entered price for a product, which could include or exclude tax. When creating a product, you
            must define the price, which serves as the default price.
        calculated_price:
          $ref: '#/components/schemas/PricingProductsPostResponsesContentApplicationJsonSchemaDataItemsCalculatedPrice'
          description: >-
            The shopper price for a product, which includes modifier, option, and option set rules. The
            `calculated_price` may include or exclude estimates for tax.
        price_range:
          $ref: '#/components/schemas/PricingProductsPostResponsesContentApplicationJsonSchemaDataItemsPriceRange'
          description: >-
            The minimum and maximum price that will typically apply to this product. Only used for complex products
            (products with variants).
        retail_price_range:
          $ref: '#/components/schemas/PricingProductsPostResponsesContentApplicationJsonSchemaDataItemsRetailPriceRange'
          description: The productʼs variants that will typically apply to this product.
        bulk_pricing:
          type: array
          items:
            $ref: '#/components/schemas/BulkPricingTier'
      description: You can use the original details of the request to identify the exact product variant and fetch prices.
      title: PricingProductsPostResponsesContentApplicationJsonSchemaDataItems
    PricingProductsPostResponsesContentApplicationJsonSchemaMeta:
      type: object
      properties: {}
      description: Response metadata.
      title: PricingProductsPostResponsesContentApplicationJsonSchemaMeta
    Products_getPrices_Response_200:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/PricingProductsPostResponsesContentApplicationJsonSchemaDataItems'
        meta:
          $ref: '#/components/schemas/PricingProductsPostResponsesContentApplicationJsonSchemaMeta'
          description: Response metadata.
      description: >-
        Note that a storeʼs [tax settings](/developer/api-reference/rest/admin/management/tax/tax-settings) may affect
        the calculations for `tax_inclusive` and `tax_exclusive` prices.
      title: Products_getPrices_Response_200
  securitySchemes:
    X-Auth-Token:
      type: apiKey
      in: header
      name: X-Auth-Token
      description: >-
        ### OAuth scopes


        | UI Name | Permission | Parameter |

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

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