Docs
Management API
Price lists
Price Lists Records

Price Lists Records

Create Batch of Price Lists Records

PUT /pricelists/records

Request

Creates a batch of Price Lists Records; may include price list records from more than one price list. Concurrency limit of 1.

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required
    The MIME type of the response body.

Body

array | application/json

  • price_list_id    integer

    The price list ID the price record is associated with.
    Example: 1

  • variant_id    integer

    The price list with which the price record is associated. Either variant_id or sku is required.
    Example: 5

  • sku    string

    The SKU for the variant with which this price record is associated. Either sku or variant_id is required.
    Example: SKU-001

  • currency    string

    The 3-letter country code with which this price record is associated.
    Example: usd

  • price    number

    The list price for the variant mapped in a Price List. Overrides any existing or Catalog list price for the variant/product. If empty, the sale price will be treated as not being set on this variant.

  • sale_price    number

    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.

  • retail_price    number

    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.

  • map_price    number

    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.

  • bulk_pricing_tiers    array[object]

example

Response

Success response for batch PUT of Price Records.

Body

object | application/json
Empty object for Success case for Batch API.

  • data    object

    Example: {}

  • meta    object

    Example: {}

example

Get All Price List Records

GET /pricelists/{price_list_id}/records

Request

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.

Authentication

  • X-Auth-Token in header

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.

  • variant_id:in in query - array
    A comma-separated list of IDs for one or more variants for which prices were requested.
    Type: array[integer]
  • product_id:in in query - array

    A comma-separated list of IDs for one or more products for which prices were requested.

    Type: array[integer]
  • currency in query - string

    Filter items by currency.

  • 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. If you provide only a limit, the API returns both paginations while applying that limit.
  • before in query - string
    A cursor that can be used for backwards pagination. Will fetch results before the position corresponding to the cursor. Cannot be used with the 'page' query parameter. Cannot be used with the 'after' query parameter.
  • after in query - string
    A cursor that can be used for forwards pagination. Will fetch results after the position corresponding to the cursor. Cannot be used with the 'page' query parameter. Cannot be used with the 'before' query parameter.
  • include in query - array

    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.

    Type: array[string]

    Allowed: bulk_pricing_tiers | sku

  • price in query - number

    Filter items by price.

  • sale_price in query - number

    Filter items by sale_price.

  • retail_price in query - number

    Filter items by retail_price.

  • map_price in query - number

    Filter items by map_price.

  • calculated_price in query - number

    Filter items by calculated_price.

  • 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
  • sku in query - string

    Filter items by SKU.

  • sku:in in query - array
    Type: array[string]
  • currency:in in query - array
    Type: array[string]
  • price:max in query - number
  • price:min in query - number
  • sale_price:max in query - number
  • sale_price:min in query - number
  • retail_price:max in query - number
  • retail_price:min in query - number
  • map_price:max in query - number
  • map_price:min in query - number
  • calculated_price:max in query - number
  • calculated_price:min in query - number
  • 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

PriceRecord Collection Response returns for:

  • Get All PriceList Records
  • Get PriceList Records by Variant ID

  • data    array[object]

  • meta    object

    'Contains data about paginating the response via cursors. If no pagination details are specified or if you only provide a limit, then both properties will be present. When a 'before' or 'after' cursor is provided, only the 'cursor_pagination' property will be present. When a 'page' parameter is provided, only the offset based 'pagination' property will be present.'

example

Upsert Price List Records

PUT /pricelists/{price_list_id}/records

Request

Creates or updates Price List Records.

Required Fields

  • currency

Notes

  • Batch requests support up to 1,000 items per request.
  • 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.
  • When updating a product with variants, or multiple SKUs, don't include records for the parent product SKU.

Authentication

  • X-Auth-Token in header

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.

  • Content-Type in header with default of application/json - string
    required
    The MIME type of the request body.

Body

array | application/json

  • variant_id    integer

    The variant ID with which this price set is associated. Either variant_id or sku is required.

    Example: 331

  • sku    string

    The SKU for the variant with which this price set is associated. Either sku or variant_id is required.

    Example: SMB-123

  • currency    string

    The 3-letter currency code with which this price set is associated.

    Example: usd

  • price    number

    The list price for the variant mapped in a Price List. Overrides any existing or Catalog list price for the variant/product.

    Example: 3.99

  • sale_price    number

    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.

    Min: 0
    Example: 3.49

  • retail_price    number

    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.

    Min: 0
    Example: 4.99

  • map_price    number

    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.

    Min: 0
    Example: 2.5

  • bulk_pricing_tiers    array[object]

example

Response

Success response for batch PUT requests of Price Records.

Body

object | application/json

  • data    object

  • meta    object

example

Delete a Price List Record

DELETE /pricelists/{price_list_id}/records

Request

Deletes a Price List Record. Deleting the records does not delete the Price List. Optional parameters can be passed in.

Authentication

  • X-Auth-Token in header

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.

  • currency in query - string
    The 3-letter currency code with which this set of prices is associated.
  • variant_id:in in query - array
    A comma-separated list of IDs for one or more variants for which prices exist.
    Type: array[integer]
  • sku:in in query - array
    A comma-separated list of SKUs for one or more variants for which prices exist.
    Type: array[string]

example

Response

Body

object | application/json
No-content response for the BigCommerce API.

  • status    integer

    204 HTTP status code.

  • title    string

    The error title describing the situation.

  • type    string

  • instance    string

example

Get Price Records by Variant

GET /pricelists/{price_list_id}/records/{variant_id}

Request

Returns Price List Records using the variant ID. Will also contain currency records.

Notes

  • Supports up to 40 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.

Authentication

  • X-Auth-Token in header

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.

  • variant_id in path - integer
    required

    ID of the variant on a product, or on an associated Price List Record.

  • include in query - array

    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.

    Type: array[string]

    Allowed: bulk_pricing_tiers | sku

  • 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. If you provide only a limit, the API returns both paginations while applying that limit.
  • before in query - string
    A cursor that can be used for backwards pagination. Will fetch results before the position corresponding to the cursor. Cannot be used with the 'page' query parameter. Cannot be used with the 'after' query parameter.
  • after in query - string
    A cursor that can be used for forwards pagination. Will fetch results after the position corresponding to the cursor. Cannot be used with the 'page' query parameter. Cannot be used with the 'before' query parameter.

example

Response

Body

object | application/json

PriceRecord Collection Response returns for:

  • Get All PriceList Records
  • Get PriceList Records by Variant ID

  • data    array[object]

  • meta    object

    'Contains data about paginating the response via cursors. If no pagination details are specified or if you only provide a limit, then both properties will be present. When a 'before' or 'after' cursor is provided, only the 'cursor_pagination' property will be present. When a 'page' parameter is provided, only the offset based 'pagination' property will be present.'

example

Get a Price Record by Currency Code

GET /pricelists/{price_list_id}/records/{variant_id}/{currency_code}

Request

Returns a Price List Record using the currency code. You can use optional parameters. Notes

  • Supports up to 50 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.

Authentication

  • X-Auth-Token in header

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.

  • variant_id in path - integer
    required

    ID of the variant on a product, or on an associated Price List Record.

  • currency_code in path - string
    required

    The currency code associated with the price record being acted upon.

  • include in query - array

    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.

    Type: array[string]

    Allowed: bulk_pricing_tiers | sku

example

Response

Body

object | application/json
Response payload for the BigCommerce API.

  • data    object

    The Price Record object.

  • meta    object

    Response metadata.

example

Set Price List Record by Currency Code

PUT /pricelists/{price_list_id}/records/{variant_id}/{currency_code}

Request

Creates or updates a Price List Record using the currency code. Notes

  • Supports up to 40 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.

Authentication

  • X-Auth-Token in header

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.

  • variant_id in path - integer
    required

    ID of the variant on a product, or on an associated Price List Record.

  • currency_code in path - string
    required

    The currency code associated with the price record being acted upon.

  • Content-Type in header with default of application/json - string
    required
    The MIME type of the request body.

Body

object | application/json
Common Price Record properties.

  • price    number

    The list price for the variant mapped in a Price List. Overrides any existing or Catalog list price for the variant/product.

    Example: 3.99

  • sale_price    number

    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.

  • retail_price    number

    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.

  • map_price    number

    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.

  • bulk_pricing_tiers    array[object]

example

Response

Body

object | application/json
Response payload for the BigCommerce API.

  • data    object

    The Price Record object.

  • meta    object

    Response metadata.

value

Delete a Price Record by Currency Code

DELETE /pricelists/{price_list_id}/records/{variant_id}/{currency_code}

Request

Deletes a Price List Record using the currency code. Note:

  • Supports up to 25 simultaneous DELETE 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.

Authentication

  • X-Auth-Token in header

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.

  • variant_id in path - integer
    required

    ID of the variant on a product, or on an associated Price List Record.

  • currency_code in path - string
    required

    The currency code associated with the price record being acted upon.

example

Response

Did you find what you were looking for?
Upsert Price List AssignmentCreate Batch of Price Lists Records