BigCommerce Price Lists Records API

openapi: 3.2.0
info:
  title: BigCommerce Price Lists Price Lists Records API
  description: 'Populate different versions of catalog pricing and assign them to different [customer groups](/docs/rest-management/customers-v2/customer-groups) at the variant level.


    ## Price Lists

    You can associate a Price List with a customer group either through the control panel or by using the [Customer Groups API](/docs/rest-management/customers-v2/customer-groups).


    You can create [Price List Assignments](/docs/rest-management/price-lists/price-lists-assignments#create-price-list-assignments) to assign Price Lists to a specific [channel](/docs/rest-management/channels/channel-listings). Price Lists assigned to a channel apply to all shoppers on that channel, unless there are more specific assignments or customer group discounts set up for the shopper''s customer group.


    If an active Price List does not contain prices for a variant, the catalog pricing will be used.

    Price Lists provide overridden price values to the Stencil storefront. You can further customize the final price display using Stencil''s [handlebars objects](/docs/storefront/stencil/themes/context/object-reference/config).


    To learn more about Price Lists, see [Price Lists API](/docs/store-operations/pricing/price-lists).


    ## Price Lists Assignments


    ### Order of operations


    **IF** Price List assigned to current customer group **AND** Price List assigned to current channel:

    * Use this Price List -- any prices not found fall back to the catalog price (or in the case of multi-currency, auto-converted prices)


    **ELSE IF** Price List assigned to current customer group:

    * Use this Price List -- any prices not found fall back to the catalog price (or in the case of multi-currency, auto-converted prices)


    **ELSE IF** Customer group discounts:

    * Use them -- any prices not found fall back to the catalog price (or in the case of multi-currency, auto-converted prices)


    **ELSE IF** Channel has a default Price List:

    * Use this Price List -- any prices not found fall back to the catalog price (or in the case of multi-currency, auto-converted prices)


    **ELSE**:

    * Fall back to the catalog price (or in the case of multi-currency, auto-converted prices)


    ## Usage notes


    - You cannot assign Price Lists to a customer group with customer group discounts -- You must delete the customer group discounts first.

    - Bulk pricing Tiers can additionally be associated with a price record to indicate different pricing as the quantity in the cart increases.

    - If a variant has a Price Record, any existing product-level bulk pricing will not apply to the cart. For variants without Price Records, any existing product bulk pricing will apply.

    - [Price Lists Records](/docs/rest-management/price-lists/price-lists-records) accepts bulk upsert. You can only do one bulk upsert at a time. Running more than one bulk upsert in parallel on the **same store** will cause a `429` error and the request will fail.

    - There are webhooks available for Price Lists assignments. The price list assignment webhook fires when a price list assignment is assigned, reassigned, or unassigned. Note that since Price Lists directly relate to products, neither product nor SKU webhooks are going to fire for corresponding changes, such as pricing.


    ## Additional information


    ### Webhooks


    * [Price list assignments](/docs/integrations/webhooks/events/channels#price-list-assignments)

    * [Products](/docs/integrations/webhooks/events#products)

    * [SKU](/docs/integrations/webhooks/events#sku)

    ### Related endpoints

    * [Get All Price Lists](/docs/rest-management/price-lists#get-all-price-lists)'
  termsOfService: https://www.bigcommerce.com/terms
  contact:
    name: BigCommerce
    url: https://www.bigcommerce.com
    email: support@bigcommerce.com
  version: ''
servers:
- url: https://api.bigcommerce.com/stores/{store_hash}/v3
  variables:
    store_hash:
      default: store_hash
      description: Permanent ID of the BigCommerce store.
  description: BigCommerce API Gateway
security:
- X-Auth-Token: []
tags:
- name: Price Lists Records
paths:
  /pricelists/records:
    parameters:
    - $ref: '#/components/parameters/Accept'
    put:
      tags:
      - Price Lists Records
      summary: BigCommerce Create Batch of Price Lists Records
      description: Creates a batch of `Price Lists Records`; may include price list records from more than one price list.  Concurrency limit of 1.
      operationId: upsertPriceListsRecords
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PriceRecordBatchItem'
        required: true
      responses:
        '200':
          description: 'Success response for batch PUT of `Price Records`.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessBatchResponse'
        '422':
          description: 'Error response for batch PUT of `Price Records`.  May include errors during partial update in non-strict mode.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PriceRecordBatchErrorResponse'
      x-codegen-request-body-name: PriceRecordBatch
  /pricelists/{price_list_id}/records:
    parameters:
    - $ref: '#/components/parameters/Accept'
    get:
      tags:
      - Price Lists Records
      summary: BigCommerce Get All Price List Records
      description: 'Returns a list of *Price List Records* associated with a *Price List*.


        **Notes**

        * Supports up to 10 simultaneous GET requests. Running more than the allowed number of requests concurrently on the same store will result in a `429` status error and your additional requests will fail.

        * Store Pricelist Records data to reduce the number of calls and maximize performance.'
      operationId: getPriceListRecords
      parameters:
      - name: price_list_id
        in: path
        description: 'The ID of the `Price List` requested.

          '
        required: true
        schema:
          type: integer
      - name: variant_id:in
        in: query
        description: The ID of the `Variant` for which prices were requested.
        schema:
          type: integer
      - name: product_id:in
        in: query
        description: 'A comma-separated list of IDs of `Product`s for which prices were requested.

          '
        schema:
          type: string
      - name: currency
        in: query
        description: 'Filter items by currency.

          '
        schema:
          type: string
          format: ISO-4217
      - name: page
        in: query
        description: Specifies the page number in a limited (paginated) list of products.
        schema:
          type: integer
      - name: limit
        in: query
        description: Controls the number of items per page in a limited (paginated) list of products.
        schema:
          type: integer
      - name: include
        in: query
        description: 'Sub-resources to include on a price record, in a comma-separated list. Valid expansions currently include `bulk_pricing_tiers` and `sku`. Other values will be ignored.

          '
        explode: false
        schema:
          type: array
          items:
            type: string
            enum:
            - bulk_pricing_tiers
            - sku
      - name: price
        in: query
        description: 'Filter items by price.

          '
        schema:
          type: number
      - name: sale_price
        in: query
        description: 'Filter items by sale_price.

          '
        schema:
          type: number
      - name: retail_price
        in: query
        description: 'Filter items by retail_price.

          '
        schema:
          type: number
      - name: map_price
        in: query
        description: 'Filter items by map_price.

          '
        schema:
          type: number
      - name: calculated_price
        in: query
        description: 'Filter items by calculated_price.

          '
        schema:
          type: number
      - name: date_created
        in: query
        description: 'Filter items by date_created.

          '
        schema:
          type: string
          format: date-time
      - name: date_modified
        in: query
        description: Filter items by date_modified. For example `v3/catalog/products?date_last_imported:min=2022-06-15`
        schema:
          type: string
          format: date-time
      - name: sku
        in: query
        description: 'Filter items by SKU.

          '
        schema:
          type: string
      - name: sku:in
        in: query
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: currency:in
        in: query
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: price:max
        in: query
        schema:
          type: number
      - name: price:min
        in: query
        schema:
          type: number
      - name: sale_price:max
        in: query
        schema:
          type: number
      - name: sale_price:min
        in: query
        schema:
          type: number
      - name: retail_price:max
        in: query
        schema:
          type: number
      - name: retail_price:min
        in: query
        schema:
          type: number
      - name: map_price:max
        in: query
        schema:
          type: number
      - name: map_price:min
        in: query
        schema:
          type: number
      - name: calculated_price:max
        in: query
        schema:
          type: number
      - name: calculated_price:min
        in: query
        schema:
          type: number
      - name: date_created:max
        in: query
        schema:
          type: string
      - name: date_created:min
        in: query
        schema:
          type: string
      - name: date_modified:max
        in: query
        schema:
          type: string
      - name: date_modified:min
        in: query
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                title: PriceRecord Collection Response
                type: object
                properties:
                  data:
                    type: array
                    items:
                      title: Price Record
                      type: object
                      description: The Price Record object.
                      allOf:
                      - type: object
                        properties:
                          calculated_price:
                            type: number
                            description: 'The price of the variant as seen on the storefront if a price record is in effect. It will be equal to the `sale_price`, if set, and the `price` if there is not a `sale_price`. Read only.

                              '
                            format: double
                            example: 24.64
                            readOnly: true
                          date_created:
                            type: string
                            description: 'The date on which the Price entry was created.

                              '
                            format: date-time
                            example: '2018-08-23T19:59:23Z'
                          date_modified:
                            type: string
                            description: 'The date on which the Price entry was created.

                              '
                            format: date-time
                            example: '2018-08-23T19:59:23Z'
                          product_id:
                            type: integer
                            description: 'The ID of the `Product` this `Price Record`ʼs `variant_id` is associated with. Read only.

                              '
                            example: 158
                            readOnly: true
                      - title: Price Record Identifiers
                        type: object
                        description: Price Record object used in batch create or update.
                        allOf:
                        - type: object
                          properties:
                            price_list_id:
                              type: integer
                              description: 'The Price List with which this price set is associated.

                                '
                              example: 2
                            variant_id:
                              type: integer
                              description: 'The variant with which this price set is associated. Either `variant_id` or `sku` is required.

                                '
                              example: 325
                            sku:
                              type: string
                              description: 'The variant with which this price set is associated. Either `sku` or `variant_id` is required.

                                '
                            currency:
                              type: string
                              description: 'The 3-letter currency code with which this price set is associated.

                                '
                              format: ISO-4217
                              example: usd
                      - title: PriceRecord Base
                        type: object
                        properties:
                          price:
                            type: number
                            description: 'The list price for the variant mapped in a Price List. Overrides any existing or Catalog list price for the variant/product.

                              '
                            format: double
                            example: 3.99
                            x-required:
                            - put
                          sale_price:
                            type: number
                            description: 'The sale price for the variant mapped in a Price List. Overrides any existing or Catalog sale price for the variant/product. If empty, the sale price will be treated as not being set on this variant.

                              '
                            format: double
                          retail_price:
                            type: number
                            description: 'The retail price for the variant mapped in a Price List. Overrides any existing or Catalog retail price for the variant/product. If empty, the retail price will be treated as not being set on this variant.

                              '
                            format: double
                          map_price:
                            type: number
                            description: 'The MAP (Minimum Advertised Price) for the variant mapped in a Price List. Overrides any existing or Catalog MAP price for the variant/product. If empty, the MAP price will be treated as not being set on this variant.

                              '
                            format: double
                          bulk_pricing_tiers:
                            type: array
                            items:
                              title: Bulk Pricing Tier
                              type: object
                              properties:
                                quantity_min:
                                  type: integer
                                  description: 'The minimum quantity of associated variant in the cart needed to qualify for this tiers pricing.

                                    '
                                  example: 1
                                quantity_max:
                                  type: integer
                                  description: 'The maximum allowed quantity of associated variant in the cart to qualify for this tiers pricing.

                                    '
                                  example: 10
                                type:
                                  type: string
                                  description: 'The type of adjustment that is made. Acceptable values: price – the adjustment amount per product; percent – the adjustment as a percentage of the original price; fixed – the adjusted absolute price of the product.

                                    '
                                  example: price
                                  enum:
                                  - fixed
                                  - price
                                  - percent
                                amount:
                                  type: number
                                  description: 'The price adjustment amount. This value along with the type will decide the price per variant for the pricing tier.

                                    '
                                  format: double
                                  example: 3
                          sku:
                            type: string
                            description: 'The SKU code associated with this `Price Record` if requested and it exists.

                              '
                            example: SMB-123
                        description: Common Price Record properties.
                  meta:
                    title: Collection Meta
                    type: object
                    properties:
                      pagination:
                        title: Pagination
                        type: object
                        properties:
                          total:
                            type: integer
                            description: 'Total number of items in the result set.

                              '
                            example: 36
                          count:
                            type: integer
                            description: 'Total number of items in the collection response.

                              '
                            example: 36
                          per_page:
                            type: integer
                            description: 'The amount of items returned in the collection per page, controlled by the limit parameter.

                              '
                            example: 50
                          current_page:
                            type: integer
                            description: 'The page you are currently on within the collection.

                              '
                            example: 1
                          total_pages:
                            type: integer
                            description: 'The total number of pages in the collection.

                              '
                            example: 1
                          links:
                            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.

                                  '
                                example: ?page=1&limit=50
                              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.

                              '
                        description: Data about the response, including pagination and collection totals.
                    description: Data about the response, including pagination and collection totals.
                description: 'PriceRecord Collection Response returns for:

                  * Get All PriceList Records

                  * Get PriceList Records by Variant ID'
              example:
                data:
                - price_list_id: 3
                  variant_id: 358
                  price: 25.48
                  sale_price: 18.57
                  retail_price: 25.48
                  map_price: 18.57
                  calculated_price: 25.48
                  date_created: '2022-09-17T20:33:14Z'
                  date_modified: '2022-09-17T20:33:14Z'
                  currency: usd
                  product_id: 187
                  bulk_pricing_tiers: []
                - price_list_id: 3
                  variant_id: 359
                  price: 31.31
                  sale_price: 31.31
                  retail_price: 31.31
                  map_price: 31.31
                  calculated_price: 31.31
                  date_created: '2022-09-17T20:33:14Z'
                  date_modified: '2022-09-17T20:33:14Z'
                  currency: usd
                  product_id: 188
                  bulk_pricing_tiers: []
                - price_list_id: 3
                  variant_id: 360
                  price: 18.57
                  sale_price: 18.57
                  retail_price: 18.57
                  map_price: 18.57
                  calculated_price: 18.57
                  date_created: '2022-09-17T20:33:14Z'
                  date_modified: '2022-09-17T20:33:14Z'
                  currency: usd
                  product_id: 189
                  bulk_pricing_tiers: []
                - price_list_id: 3
                  variant_id: 361
                  price: 22.54
                  sale_price: 22.54
                  retail_price: 22.54
                  map_price: 22.54
                  calculated_price: 22.54
                  date_created: '2022-09-17T20:33:14Z'
                  date_modified: '2022-09-17T20:33:14Z'
                  currency: usd
                  product_id: 190
                  bulk_pricing_tiers: []
                - price_list_id: 3
                  variant_id: 362
                  price: 27.39
                  sale_price: 27.39
                  retail_price: 27.39
                  map_price: 27.39
                  calculated_price: 27.39
                  date_created: '2022-09-17T20:33:14Z'
                  date_modified: '2022-09-17T20:51:26Z'
                  currency: usd
                  product_id: 191
                  bulk_pricing_tiers:
                  - quantity_min: 10
                    quantity_max: 19
                    type: percent
                    amount: 1
                  - quantity_min: 20
                    quantity_max: 29
                    type: percent
                    amount: 3
                  - quantity_min: 30
                    quantity_max: 2147483647
                    type: percent
                    amount: 5
                - price_list_id: 3
                  variant_id: 382
                  price: 9.8
                  sale_price: 9.8
                  retail_price: 9.8
                  map_price: 9.8
                  calculated_price: 9.8
                  date_created: '2022-09-17T20:33:14Z'
                  date_modified: '2022-09-17T20:33:14Z'
                  currency: usd
                  product_id: 192
                  bulk_pricing_tiers: []
                - price_list_id: 3
                  variant_id: 383
                  price: 24.5
                  sale_price: 24.5
                  retail_price: 24.5
                  map_price: 24.5
                  calculated_price: 24.5
                  date_created: '2022-09-17T20:33:14Z'
                  date_modified: '2022-09-17T20:33:14Z'
                  currency: usd
                  product_id: 192
                  bulk_pricing_tiers: []
                - price_list_id: 3
                  variant_id: 384
                  price: 24.5
                  sale_price: 24.5
                  retail_price: 24.5
                  map_price: 24.5
                  calculated_price: 24.5
                  date_created: '2022-09-17T20:33:14Z'
                  date_modified: '2022-09-17T20:33:14Z'
                  currency: usd
                  product_id: 192
                  bulk_pricing_tiers: []
                - price_list_id: 3
                  variant_id: 385
                  price: 9.8
                  sale_price: 9.8
                  retail_price: 9.8
                  map_price: 9.8
                  calculated_price: 9.8
                  date_created: '2022-09-17T20:33:14Z'
                  date_modified: '2022-09-17T20:33:14Z'
                  currency: usd
                  product_id: 193
                  bulk_pricing_tiers: []
                - price_list_id: 3
                  variant_id: 386
                  price: 10.78
                  sale_price: 10.78
                  retail_price: 10.78
                  map_price: 10.78
                  calculated_price: 10.78
                  date_created: '2022-09-17T20:33:14Z'
                  date_modified: '2022-09-17T20:33:14Z'
                  currency: usd
                  product_id: 194
                  bulk_pricing_tiers: []
                - price_list_id: 3
                  variant_id: 388
                  price: 10.78
                  sale_price: 10.78
                  retail_price: 10.78
                  map_price: 10.78
                  calculated_price: 10.78
                  date_created: '2022-09-17T20:33:14Z'
                  date_modified: '2022-09-17T20:35:42Z'
                  currency: usd
                  product_id: 195
                  bulk_pricing_tiers:
                  - quantity_min: 2
                    quantity_max: 9
                    type: percent
                    amount: 1
                  - quantity_min: 10
                    quantity_max: 19
                    type: percent
                    amount: 2
                  - quantity_min: 20
                    quantity_max: 2147483647
                    type: percent
                    amount: 3
                - price_list_id: 3
                  variant_id: 389
                  price: 18.62
                  sale_price: 18.62
                  retail_price: 18.62
                  map_price: 18.62
                  calculated_price: 18.62
                  date_created: '2022-09-17T20:33:14Z'
                  date_modified: '2022-09-17T20:35:42Z'
                  currency: usd
                  product_id: 195
                  bulk_pricing_tiers:
                  - quantity_min: 2
                    quantity_max: 9
                    type: percent
                    amount: 1
                  - quantity_min: 10
                    quantity_max: 19
                    type: percent
                    amount: 2
                  - quantity_min: 20
                    quantity_max: 2147483647
                    type: percent
                    amount: 3
                - price_list_id: 3
                  variant_id: 390
                  price: 10.78
                  sale_price: 10.78
                  retail_price: 10.78
                  map_price: 10.78
                  calculated_price: 10.78
                  date_created: '2022-09-17T20:33:14Z'
                  date_modified: '2022-09-17T20:35:42Z'
                  currency: usd
                  product_id: 195
                  bulk_pricing_tiers:
                  - quantity_min: 2
                    quantity_max: 9
                    type: percent
                    amount: 1
                  - quantity_min: 10
                    quantity_max: 19
                    type: percent
                    amount: 2
                  - quantity_min: 20
                    quantity_max: 2147483647
                    type: percent
                    amount: 3
                - price_list_id: 3
                  variant_id: 391
                  price: 10.78
                  sale_price: 10.78
                  retail_price: 10.78
                  map_price: 10.78
                  calculated_price: 10.78
                  date_created: '2022-09-17T20:33:14Z'
                  date_modified: '2022-09-17T20:35:42Z'
                  currency: usd
                  product_id: 195
                  bulk_pricing_tiers:
                  - quantity_min: 2
                    quantity_max: 9
                    type: percent
                    amount: 1
                  - quantity_min: 10
                    quantity_max: 19
                    type: percent
                    amount: 2
                  - quantity_min: 20
                    quantity_max: 2147483647
                    type: percent
                    amount: 3
                meta:
                  pagination:
                    total: 14
                    count: 14
                    per_page: 50
                    current_page: 1
                    total_pages: 1
        '429':
          description: 'Allowed number of requests exceeded.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    status: 429
                    title: Too many requests
                    type: /api-docs/getting-started/api-status-codes
                    errors: {}
            examples: {}
    put:
      tags:
      - Price Lists Records
      summary: BigCommerce Upsert Price List Records
      description: "Creates or updates *Price List Records*. \n\n**Required Fields**\n* currency\n\n**Notes**\n* Batch requests support up to 1,000 items per request.\n* Up to 2 concurrent batch upsert requests are supported with this API. Running more than the allowed concurrent requests in parallel on the **same store** will cause a `429` error, and your additional requests will fail. You are encouraged to run requests sequentially with as many records per request as possible to maximize performance.\n* When updating a product with variants, or multiple SKUs, don't include records for the parent product SKU."
      operationId: upsertPriceListRecords
      parameters:
      - name: price_list_id
        in: path
        description: 'The ID of the `Price List` requested.

          '
        required: true
        schema:
          type: integer
      - $ref: '#/components/parameters/ContentType'
      requestBody:
        content:
          application/json:
            schema:
              title: Price Record Collection Put
              type: array
              items:
                title: PriceRecord Batch Item
                description: Price Record object used in batch create or update.
                allOf:
                - properties:
                    variant_id:
                      type: integer
                      description: 'The variant ID with which this price set is associated. Either `variant_id` or `sku` is required.

                        '
                      example: 331
                    sku:
                      type: string
                      description: 'The SKU for the variant with which this price set is associated. Either `sku` or `variant_id` is required.

                        '
                      example: SMB-123
                    currency:
                      type: string
                      description: 'The 3-letter currency code with which this price set is associated.

                        '
                      format: ISO-4217
                      example: usd
                - title: PriceRecord Base
                  description: Common Price Record properties.
                  properties:
                    price:
                      type: number
                      description: 'The list price for the variant mapped in a Price List. Overrides any existing or Catalog list price for the variant/product.

                        '
                      format: double
                      example: 3.99
                      x-required:
              

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