Docs
Management API
Price lists

Price Lists

Populate different versions of catalog pricing and assign them to different 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.

You can create Price List Assignments to assign Price Lists to a specific channel. 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.

To learn more about Price Lists, see Price Lists API.

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

Related endpoints

Get All Price Lists

GET /pricelists

Request

Returns a list of Price Lists. Optional parameters can be passed in.

Authentication

  • X-Auth-Token in header
    required

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required

    The MIME type of the response body.

  • id in query - integer

    Filter items by ID.

  • name in query - string

    Filter items by name.

  • date_created in query - string

    Filter items by date_created.

  • date_modified in query - string

    Filter items by date_modified. For example v3/catalog/products?date_last_imported:min=2018-06-15

  • page in query - integer

    Specifies the page number in a limited (paginated) list of products.

  • limit in query - integer

    Controls the number of items per page in a limited (paginated) list of products.

  • id:in in query - array

    Type: array[integer]

  • name:like in query - string
  • date_created:max in query - string
  • date_created:min in query - string
  • date_modified:max in query - string
  • date_modified:min in query - string

example

Response

Body

object | application/json

Get All PriceLists.

  • data    array[object]

  • meta    object

    Data related to the response, including pagination and collection totals.

example

Create a Price List

POST /pricelists

Request

Creates a Price List.

Required Fields

  • name

Authentication

  • X-Auth-Token in header
    required

Parameters

  • store_hash in path - string
  • Content-Type in header with default of application/json - string
    required

    The MIME type of the request body.

Body

application/json

Creates a Price List.

  • name    string
    required

    The unique name of the Price List. Required in a POST request.

    Example: Wholesale

  • active    boolean

    Boolean value that specifies whether this Price List and its prices are active or not. Defaults to true.

    Example: true

  • name    string
    required

    The unique name of the Price List. Required in a POST request.

    Example: Wholesale

  • active    boolean

    Boolean value that specifies whether this Price List and its prices are active or not. Defaults to true.

    Example: true

example

Response

Body

object | application/json

PriceList Response returns for:

  • Create a PriceList
  • Get a PriceList
  • Update a PriceList

  • data

  • meta    object

    Response metadata.

example

Delete All Price Lists

DELETE /pricelists

Request

Deletes a Price List. All associated price records are also removed. Optional parameters can be passed in.

Authentication

  • X-Auth-Token in header
    required

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required

    The MIME type of the response body.

  • id:in in query - array

    Filter by ID. Accepts multiple comma-separated values.

    Type: array[integer]

  • name in query - string

    Filter items by name.

example

Response

204 No Content. The action has been performed and no further information will be supplied. null is returned.

Body

object | application/json

    example

    Get a Price List

    GET /pricelists/{price_list_id}

    Request

    Returns a single Price List.

    Authentication

    • X-Auth-Token in header
      required

    Parameters

    • store_hash in path - string
    • Accept in header with default of application/json - string
      required

      The MIME type of the response body.

    • price_list_id in path - integer
      required

      The ID of the Price List requested.

    • id in query - integer

      Filter items by ID.

    • name in query - string

      Filter items by name.

    • date_created in query - string

      Filter items by date_created.

    • date_modified in query - string

      Filter items by date_modified. For example v3/catalog/products?date_last_imported:min=2022-06-15

    • page in query - integer

      Specifies the page number in a limited (paginated) list of products.

    • limit in query - integer

      Specifies the number of items per page in a limited (paginated) list of products.

    example

    Response

    Body

    object | application/json

    PriceList Response returns for:

    • Create a PriceList
    • Get a PriceList
    • Update a PriceList

    • data      object

      Specifies the Common Price List properties.

    • meta      object

      Response metadata.

    example

    Update a Price List

    PUT /pricelists/{price_list_id}

    Request

    Updates a Price List.

    Authentication

    • X-Auth-Token in header
      required

    Parameters

    • store_hash in path - string
    • price_list_id in path - integer
      required

      The ID of the Price List requested.

    • Content-Type in header with default of application/json - string
      required

      The MIME type of the request body.

    Body

    application/json

    Update a PriceList

    • name      string
      required

      The unique name of the Price List. Required in a POST request.

      Example: Wholesale

    • active      boolean

      Whether or not this Price List and its prices are active. Defaults to true.

      Example: true

    • name      string
      required

      The unique name of the Price List. Required in a POST request.

      Example: Wholesale

    • active      boolean

      Whether or not this Price List and its prices are active. Defaults to true.

      Example: true

    example

    Response

    Body

    object | application/json

    PriceList Response returns for:

    • Create a PriceList
    • Get a PriceList
    • Update a PriceList

    • data

    • meta      object

      Response metadata.

    example

    Delete a Price List

    DELETE /pricelists/{price_list_id}

    Request

    Deletes a Price List. All associated price records are also removed. Limits

    • Limit of 1 concurrent request.

    Authentication

    • X-Auth-Token in header
      required

    Parameters

    • store_hash in path - string
    • Accept in header with default of application/json - string
      required

      The MIME type of the response body.

    • price_list_id in path - integer
      required

      The ID of the Price List requested.

    example

    Response

    Action has been enacted and no further information is to be supplied. null is returned.

    Did you find what you were looking for?
    Get Prices (Batch)Get All Price Lists