Price Lists
Create Batch of Price Lists Records
PUT /stores/{store_hash}/v3/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 headerrequired
Parameters
- store_hash in path - string
- Accept in header with default of application/json - stringrequired
The MIME type of the response body.
Body
price_list_idinteger
The price list ID the price record is associated with.
Example: 1
variant_idinteger
The price list with which the price record is associated. Either
variant_id
orsku
is required.Example: 5
skustring
The SKU for the variant with which this price record is associated. Either
sku
orvariant_id
is required.Example: SKU-001
currencystring
The 3-letter country code with which this price record is associated.
Example: usd
itemsobject
Common Price Record properties.
example
Response
Success response for batch PUT of Price Records
.
Body
Empty object for Success case for Batch API.
dataobject
Example: {}
metaobject
Example: {}
example
Get All Price List Records
GET /stores/{store_hash}/v3/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 headerrequired
Parameters
- store_hash in path - string
- Accept in header with default of application/json - stringrequired
The MIME type of the response body.
- price_list_id in path - integerrequired
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.
- product_id:in in query - array
A comma-separated list of IDs for one or more products for which prices were requested.
- 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
andsku
. Other values will be ignored. - 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
- currency:in in query - array
- 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
PriceRecord Collection Response returns for:
- Get All PriceList Records
- Get PriceList Records by Variant ID
dataarray[object]
metaobject
Data about the response, including pagination and collection totals.
example
Upsert Price List Records
PUT /stores/{store_hash}/v3/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 headerrequired
Parameters
- store_hash in path - string
- price_list_id in path - integerrequired
The ID of the
Price List
requested. - Content-Type in header with default of application/json - stringrequired
The MIME type of the request body.
Body
variant_idinteger
The variant ID with which this price set is associated. Either
variant_id
orsku
is required.Example: 331
skustring
The SKU for the variant with which this price set is associated. Either
sku
orvariant_id
is required.Example: SMB-123
currencystring
The 3-letter currency code with which this price set is associated.
Example: usd
pricenumber
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_pricenumber
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_pricenumber
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_pricenumber
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_tiersarray[object]
skustring
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
dataobject
metaobject
example
Delete a Price List Record
DELETE /stores/{store_hash}/v3/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 headerrequired
Parameters
- store_hash in path - string
- Accept in header with default of application/json - stringrequired
The MIME type of the response body.
- price_list_id in path - integerrequired
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.
example
Response
Body
No-content response for the BigCommerce API.
statusinteger
204 HTTP status code.
titlestring
The error title describing the situation.
typestring
instancestring
example
Get Price Records by Variant
GET /stores/{store_hash}/v3/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 headerrequired
Parameters
- store_hash in path - string
- Accept in header with default of application/json - stringrequired
The MIME type of the response body.
- price_list_id in path - integerrequired
The ID of the
Price List
requested. - variant_id in path - integerrequired
ID of the variant on a product, or on an associated Price List Record.
example
Response
Body
PriceRecord Collection Response returns for:
- Get All PriceList Records
- Get PriceList Records by Variant ID
dataarray[object]
metaobject
Data related to the response, including pagination and collection totals.
example
Get a Price Record by Currency Code
GET /stores/{store_hash}/v3/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 headerrequired
Parameters
- store_hash in path - string
- Accept in header with default of application/json - stringrequired
The MIME type of the response body.
- price_list_id in path - integerrequired
The ID of the
Price List
requested. - variant_id in path - integerrequired
ID of the variant on a product, or on an associated Price List Record.
- currency_code in path - stringrequired
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
andsku
. Other values will be ignored.
example
Response
Body
Response payload for the BigCommerce API.
dataobject
The Price Record object.
metaobject
Response metadata.
example
Set Price List Record by Currency Code
PUT /stores/{store_hash}/v3/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 headerrequired
Parameters
- store_hash in path - string
- price_list_id in path - integerrequired
The ID of the
Price List
requested. - variant_id in path - integerrequired
ID of the variant on a product, or on an associated Price List Record.
- currency_code in path - stringrequired
The currency code associated with the price record being acted upon.
- Content-Type in header with default of application/json - stringrequired
The MIME type of the request body.
Body
pricenumber
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_pricenumber
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_pricenumber
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_pricenumber
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_tiersarray[object]
skustring
The SKU code associated with this
Price Record
if requested and it exists.Example: SMB-123
example
Response
Body
Response payload for the BigCommerce API.
dataobject
The Price Record object.
metaobject
Response metadata.
value
Delete a Price Record by Currency Code
DELETE /stores/{store_hash}/v3/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 headerrequired
Parameters
- store_hash in path - string
- Accept in header with default of application/json - stringrequired
The MIME type of the response body.
- price_list_id in path - integerrequired
The ID of the
Price List
requested. - variant_id in path - integerrequired
ID of the variant on a product, or on an associated Price List Record.
- currency_code in path - stringrequired
The currency code associated with the price record being acted upon.