BigCommerce Price Lists Records API

openapi: 3.0.0
info:
  title: BigCommerce Abandoned Cart Emails Price Lists Records API
  version: 3.0.0
  termsOfService: https://www.bigcommerce.com/terms
  description: Abandoned Cart Emails V3 API managing Handlebars-based emails.
  contact:
    name: BigCommerce
    url: https://www.bigcommerce.com
    email: support@bigcommerce.com
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:
                      - 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
                      minimum: 0
                      example: 3.49
                    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
                      minimum: 0
                      example: 4.99
                    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
                      minimum: 0
                      example: 2.5
                    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 the pricing of this tier.

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

                              '
                            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
                type: object
        required: true
        description: ''
      responses:
        '200':
          description: Success response for batch PUT requests of Price Records.
          content:
            application/json:
              schema:
                title: Price Records respons

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