BigCommerce Price Lists Assignments API

openapi: 3.2.0
info:
  title: BigCommerce Price Lists Price Lists Assignments 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 Assignments
paths:
  /pricelists/assignments:
    parameters:
    - $ref: '#/components/parameters/Accept'
    get:
      tags:
      - Price Lists Assignments
      summary: BigCommerce Get Price List Assignments
      description: Fetches an array of `Price List Assignments` matching a particular Customer Group and Price List and Channel.
      operationId: getListOfPriceListAssignments
      parameters:
      - name: id
        in: query
        description: The ID of the `Price List Assignment`.
        schema:
          type: integer
      - name: price_list_id
        in: query
        description: The ID of the `Price List`.
        schema:
          type: integer
      - name: customer_group_id
        in: query
        description: The ID of the `Customer Group`.
        schema:
          type: integer
      - name: channel_id
        in: query
        description: The ID of the `Channel`.
        schema:
          type: integer
      - name: id:in
        in: query
        description: Filter items by a comma-separated list of `id`s.
        style: form
        explode: false
        schema:
          type: array
          items:
            type: integer
      - name: customer_group_id:in
        in: query
        description: Filter items by a comma-separated list of `customer_group_id`s.
        style: form
        explode: false
        schema:
          type: array
          items:
            type: integer
      - name: price_list_id:in
        in: query
        description: Filter items by a comma-separated list of `price_list_id`s.
        style: form
        explode: false
        schema:
          type: array
          items:
            type: integer
      - name: channel_id:in
        in: query
        description: Filter items by a comma-separated list of `channel_id`s.
        style: form
        explode: false
        schema:
          type: array
          items:
            type: integer
      - 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
      responses:
        '200':
          description: An array of price list assignments and metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssignmentsForGetResponse'
    post:
      tags:
      - Price Lists Assignments
      description: "Creates a batch of `Price List Assignments`. \n**Note:** The batch limit for `Price List Assignments` is 25."
      summary: BigCommerce Create Price List Assignments
      operationId: createPriceListAssignments
      parameters:
      - $ref: '#/components/parameters/ContentType'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBatchPriceListAssignmentsRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessBatchResponse'
        '422':
          description: Error response. Includes the errors for each reference ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PriceListAssignmentsBatchErrorResponse'
    delete:
      tags:
      - Price Lists Assignments
      summary: BigCommerce Delete Price List Assignments
      description: 'Deletes one or more `Price List Assignments` objects from BigCommerce using a query parameter. You must use at least one query parameter. '
      operationId: deletePriceListAssignments
      parameters:
      - $ref: '#/components/parameters/FilterAssignmentIdParam'
      - $ref: '#/components/parameters/FilterPriceListIdParam'
      - $ref: '#/components/parameters/FilterCustomerGroupIdParam'
      - $ref: '#/components/parameters/FilterChannelIdParam'
      - $ref: '#/components/parameters/ChannelIdInParam'
      responses:
        '204':
          description: No Content.
  /pricelists/{price_list_id}/assignments:
    parameters:
    - $ref: '#/components/parameters/Accept'
    put:
      tags:
      - Price Lists Assignments
      description: 'Upsert a single `Price List Assignment` for a `Price List`.

        **Note:**

        * Supports up to 25 simultaneous PUT 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.        '
      summary: BigCommerce Upsert Price List Assignment
      operationId: upsertPriceListAssignment
      parameters:
      - $ref: '#/components/parameters/PriceListIdParam'
      - $ref: '#/components/parameters/ContentType'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssignmentForPutRequest'
        required: true
      responses:
        '200':
          description: A price list assignment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssignmentForPutResponse'
        '404':
          description: A matching customer group or channel wasnʼt found, so no assignment is created or returned.
components:
  schemas:
    AssignmentsForRequest:
      type: object
      description: '`Price List Assignments` object used in a batch create request.'
      x-internal: false
      properties:
        price_list_id:
          type: integer
          format: int32
          description: Price list ID for assignment.
          example: 1
        customer_group_id:
          type: integer
          format: int32
          description: Customer group ID for assignment.
          example: 2
        channel_id:
          type: integer
          format: int32
          description: Channel ID for assignment
          example: 1
      required:
      - price_list_id
    AssignmentForPutResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            id:
              type: integer
              format: int32
              description: Unique identifier for this price list assignment.
              example: 1
            price_list_id:
              type: integer
              format: int32
              description: Price list ID for assignment.
              example: 1
            customer_group_id:
              type: integer
              format: int32
              description: Customer group ID for assignment.
              example: 2
            channel_id:
              type: integer
              format: int32
              description: Channel ID for assignment.
              example: 2
        meta:
          $ref: '#/components/schemas/Meta'
    CreateBatchPriceListAssignmentsRequest:
      type: array
      description: Batch of price list assignments.
      items:
        $ref: '#/components/schemas/AssignmentsForRequest'
      x-internal: false
    AssignmentForGetResponse:
      type: object
      x-internal: false
      properties:
        id:
          type: integer
          format: int32
          description: Unique identifier for this price list assignment.
          example: 1
        price_list_id:
          type: integer
          format: int32
          description: Pricelist ID for assignment.
          example: 1
        customer_group_id:
          type: integer
          format: int32
          description: Customer group ID for assignment.
          example: 2
        channel_id:
          type: integer
          format: int32
          description: Channel ID for assignment.
          example: 2
    AssignmentForPutRequest:
      type: object
      properties:
        customer_group_id:
          type: integer
          format: int32
          description: Customer group ID for assignment.
          example: 2
        channel_id:
          type: integer
          format: int32
          description: Channel ID for assignment
          example: 1
      required:
      - customer_group_id
      - channel_id
    SuccessBatchResponse:
      type: object
      description: Empty object for Success case for Batch API.
      properties:
        data:
          type: object
          example: {}
        meta:
          type: object
          example: {}
    AssignmentsForGetResponse:
      description: Array of the price list assignments matching the filter. The response is paginated.
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/AssignmentForGetResponse'
        meta:
          $ref: '#/components/schemas/CollectionMeta'
      x-internal: false
    CollectionMeta:
      type: object
      description: Data related the response, including pagination and collection totals.
      properties:
        pagination:
          type: object
          description: Data related to the response, including pagination and collection totals.
          title: Pagination
          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
              description: 'Pagination links for the previous and next parts of the whole collection.

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

                    '
      title: Collection Meta
      x-internal: false
    PriceListAssignmentsBatchErrorResponse:
      type: object
      x-internal: false
      properties:
        status:
          type: integer
        title:
          type: string
        type:
          type: string
        errors:
          type: object
          properties: {}
          additionalProperties: true
          title: Detailed Errors
        meta:
          type: object
          properties:
            saved_records:
              type: integer
    Meta:
      title: Response meta
      type: object
      properties: {}
      additionalProperties: true
      description: Response metadata.
  parameters:
    Accept:
      name: Accept
      in: header
      required: true
      description: The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body.
      schema:
        type: string
        default: application/json
    FilterChannelIdParam:
      name: channel_id
      description: The ID of the `Channel`.
      required: false
      in: query
      schema:
        type: integer
    FilterPriceListIdParam:
      name: price_list_id
      description: The ID of the `Price List`.
      required: false
      in: query
      schema:
        type: integer
    ContentType:
      name: Content-Type
      in: header
      required: true
      description: The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the request body.
      schema:
        type: string
        default: application/json
    PriceListIdParam:
      schema:
        type: integer
      name: price_list_id
      in: path
      description: 'The ID of the `Price List` requested.

        '
      required: true
    ChannelIdInParam:
      in: query
      name: channel_id:in
      description: Filter results by a comma-separated list of `channel_id`s.
      schema:
        type: string
    FilterAssignmentIdParam:
      description: The ID of the `Price List Assignment`.
      required: false
      in: query
      schema:
        type: integer
      name: id
    FilterCustomerGroupIdParam:
      name: customer_group_id
      description: The ID of the `Customer Group`.
      required: false
      in: query
      schema:
        type: integer
  securitySchemes:
    X-Auth-Token:
      name: X-Auth-Token
      description: '### OAuth scopes


        | UI Name | Permission | Parameter |

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

        |  Products | modify | `store_v2_products` |

        |  Products | read-only | `store_v2_products_read_only` |


        ### Authentication header


        | Header | Argument | Description |

        |:-|:|:|

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


        ### Further reading


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


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


        For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes).'
      type: apiKey
      in: header