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.
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
andsku
. 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 - arrayType: array[string]
- currency:in in query - arrayType: 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
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.
Type: array[integer]
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.Type: array[string]Allowed: bulk_pricing_tiers | sku
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.