Guide · Price list import

Price lists

Set customer-group pricing across a catalog from one spreadsheet. Price records are written in batches of up to a thousand, and BigCommerce caps how many of those may run at once — so this is the one import type that deliberately does not run in parallel.

A price list is a named set of prices that can be attached to one or more customer groups. The list itself is one thing; the prices inside it are another, and one row of your file can create either or both.

Commands

Command	Description	Behaviour
MERGE	Create or update.	The default. Creates the price list if the store has none by that name, then upserts the price.
NEW	Same as MERGE for prices.	The records endpoint is an upsert with no create-versus-update distinction, so pretending otherwise would be a fiction.
UPDATE	Update an existing price.	Never creates the price list — a row naming a list that does not exist fails and says so.
DELETE	Remove one price.	Removes the price for that variant in that currency. Needs a `Variant ID`, or a `SKU` this app can resolve to one.
IGNORE	Skip this row.	Does nothing, and is recorded as skipped rather than as a success.
REPLACE	Refused.	Fails the row. There is nothing a delete-then-create would achieve that an upsert does not.

Columns

Column	Notes
`Price List`	The list's name. Unique on BigCommerce, so it identifies one list and travels between stores.
`Price List ID`	Wins over the name when both are given.
`Price List Active`	`true` or `false`. A row carrying only this and a list name switches the list on or off without touching any price.
`SKU`	The variant's SKU. BigCommerce accepts it in place of a variant id on the upsert, which is what makes this file writable by hand.
`Variant ID`	Exact. Preferred over `SKU` when both are given.
`Currency`	Required on any row that carries a price. Three-letter code, e.g. `USD`.
`Price`	The price for this variant in this list.
`Sale Price`, `Retail Price`, `MAP Price`	Optional, and each is left alone when its cell is blank.
`Bulk Pricing Min Quantity`, `Bulk Pricing Type`, `Bulk Pricing Amount`	One quantity tier per row, the way product bulk pricing works.

A minimal file

Command,Price List,SKU,Currency,Price
MERGE,Wholesale,TSHIRT-M,USD,15.50
MERGE,Wholesale,TSHIRT-L,USD,15.50
MERGE,Wholesale,HOODIE-M,USD,32.00

That creates a price list called Wholesale if the store has none, then sets three prices in it. Running the same file again changes nothing — the endpoint is an upsert, so a re-run is safe.

Why this import does not run in parallel

Everywhere else, this app runs four queue workers because the work is network-bound and BigCommerce allows far more requests than one worker can make. Price lists are the exception, and it is the platform's decision rather than a design choice here.

The practical effect is that a very large price file is steadier but not faster than it would be unchained — which is exactly what BigCommerce asks for, since it also recommends packing as many records into each request as possible. A batch here carries up to 250 records against a documented cap of 1,000.

Deleting a price

The delete endpoint is keyed by variant id and currency, so a row naming only a SKU has to have it resolved first.

Command,Price List,SKU,Currency
DELETE,Wholesale,TSHIRT-M,USD

If the SKU has no price in that list there is nothing to delete, and the row says so rather than reporting a success.

Export

An export writes one row per price record, plus a row for any price list that has no prices in it — otherwise re-importing the file would quietly drop the list itself and you would have to re-create it by hand.