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

[
{
"price_list_id": 1,
"variant_id": 5,
"sku": "SKU-001",
"currency": "usd",
"price": 0,
"sale_price": 0,
"retail_price": 0,
"map_price": 0,
"bulk_pricing_tiers": [
{
"quantity_min": 1,
"quantity_max": 10,
"type": "fixed",
"amount": 0
}
]
}
]

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

{
"data": {},
"meta": {}
}

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

curl --request GET \
--url 'https://api.bigcommerce.com/stores/[store_hash]/v3/pricelists/[price_list_id]/records' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-Auth-Token: {{token}}'

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

{
"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",

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

[
{
"variant_id": 331,
"sku": "SMB-123",
"currency": "usd",
"price": 3.99,
"sale_price": 3.49,
"retail_price": 4.99,
"map_price": 2.5,
"bulk_pricing_tiers": [
{
"quantity_min": 1,
"quantity_max": 10,
"type": "price",
"amount": 3
}
]
}
]

Response

Success response for batch PUT requests of Price Records.

Body

object | application/json

  • data    object

  • meta    object

example

{
"data": {},
"meta": {}
}

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

curl --request DELETE \
--url 'https://api.bigcommerce.com/stores/[store_hash]/v3/pricelists/[price_list_id]/records' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-Auth-Token: {{token}}'

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

{
"status": 0,
"title": "string",
"type": "string",
"instance": "string"
}

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

example

curl --request GET \
--url 'https://api.bigcommerce.com/stores/[store_hash]/v3/pricelists/[price_list_id]/records/[variant_id]' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-Auth-Token: {{token}}'

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

{
"data": [
{
"date_created": "2022-08-23T19:59:23Z",
"date_modified": "2022-08-23T19:59:23Z",
"price_list_id": 2,
"variant_id": 325,
"sku": "SMB-123",
"currency": "usd",
"price": 3.99,
"sale_price": 5.99,
"retail_price": 6.99,
"map_price": 5.99,
"bulk_pricing_tiers": [
{
"quantity_min": 1,
"quantity_max": 10,
"type": "price",
"amount": 3
}
]
}
],
"meta": {
"pagination": {
"total": 36,
"count": 36,
"per_page": 50,
"current_page": 1,

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

curl --request GET \
--url 'https://api.bigcommerce.com/stores/[store_hash]/v3/pricelists/[price_list_id]/records/[variant_id]/[currency_code]' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-Auth-Token: {{token}}'

Response

Body

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

  • data    object

    The Price Record object.

  • meta    object

    Response metadata.

example

{
"data": {
"price_list_id": 4,
"variant_id": 356,
"price": 22.544,
"sale_price": 22.544,
"retail_price": 22.544,
"map_price": 22.544,
"calculated_price": 22.544,
"date_created": "2022-09-18T13:18:15Z",
"date_modified": "2022-09-18T13:18:15Z",
"currency": "eur",
"product_id": 185
},
"meta": {
"pagination": {
"total": 1,
"count": 1,
"per_page": 50,
"current_page": 1,
"total_pages": 1
}
}
}

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

{
"price": 3.99,
"sale_price": 0.1,
"retail_price": 0.1,
"map_price": 0.1,
"bulk_pricing_tiers": [
{
"quantity_min": 1,
"quantity_max": 10,
"type": "price",
"amount": 3
}
]
}

Response

Body

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

  • data    object

    The Price Record object.

  • meta    object

    Response metadata.

value

{
"data": {
"price_list_id": 4,
"variant_id": 356,
"price": 12.99,
"sale_price": 10.99,
"retail_price": 15.99,
"map_price": 17.99,
"calculated_price": 10.99,
"date_created": "2022-09-18T13:18:15Z",
"date_modified": "2022-09-18T13:30:48Z",
"currency": "eur",
"product_id": 185,
"bulk_pricing_tiers": [
{
"quantity_min": 5,
"quantity_max": 10,
"type": "percent",
"amount": 1
},
{
"quantity_min": 11,
"quantity_max": 20,
"type": "percent",
"amount": 2
}
]
},
"meta": {}

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

curl --request DELETE \
--url 'https://api.bigcommerce.com/stores/[store_hash]/v3/pricelists/[price_list_id]/records/[variant_id]/[currency_code]' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-Auth-Token: {{token}}'

Response

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