Docs
Management API
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
    required

Parameters

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

    The MIME type of the response body.

Body

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

  • items
    object

    Common Price Record properties.

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

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

  • 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

    Data about the response, including pagination and collection totals.

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

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.

    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.

    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.

    Example: 2.5

  • bulk_pricing_tiers
    array[object]

  • sku
    string

    The SKU code associated with this Price Record if requested and it exists.

    Example: SMB-123

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

    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.

    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.

    Example: 2.5

  • bulk_pricing_tiers
    array[object]

  • sku
    string

    The SKU code associated with this Price Record if requested and it exists.

    Example: SMB-123

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

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

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

  • variant_id in path - integer
    required

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

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

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

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

  • 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

    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
    required

Parameters

  • store_hash in path - string
  • 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

application/json
  • 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]

  • sku
    string

    The SKU code associated with this Price Record if requested and it exists.

    Example: SMB-123

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

  • sku
    string

    The SKU code associated with this Price Record if requested and it exists.

    Example: SMB-123

example

Response

Body

object | application/json

Response payload for the BigCommerce API.

  • data

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

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