Price lists, bulk edits and imports

Every price list with its header and its rules. A price list is a named set of prices that applies to the shoppers its rules name — a trade list, a wholesale list, a members' list — which is what makes it a different thing from a sale: a sale is a discount every shopper gets and the catalog advertises, a price list is a price. kind is override (what this variant costs for this shopper) or sale (a cut, which is barred from supplying the strikethrough reference price). live says whether the list is active and inside its window right now. Price rows are not listed here; ask get_price_list for one list's.

One price list with its rules in order and every price row it holds, variant by variant and rung by rung. Amounts come back both as amount_minor and as a decimal amount.

Create a named set of prices. name is required and is never shown to a shopper. Rules decide who the list applies to and are joined with AND, so a list with no rules applies to everyone; each rule is an attribute from list_rule_attributes, an operator that attribute offers, and a value. An attribute the vocabulary does not publish is refused, naming the key. Prices are the rows the list charges: one per variant per quantity range, with min_quantity starting the rung and max_quantity ending it or omitted for an open-ended top rung. A rung is a price, not a discount. Rungs for one variant may not overlap. A row names its variant by variant_id or by sku in its place, never both; a SKU no variant carries, or one two variants share, is refused with 422 naming it. On a store that sells in more than one currency, currency makes the list in that currency, and every price on it is in it.

Change a price list's header, its rules, its prices, or any combination. Sending rules replaces the whole set, empty list included, which is how the last rule is removed; omitting it leaves the rules standing. prices follows the same three-state contract, so switching a list off is one field and not a round trip through every price. A price row names its variant by variant_id or by sku, as create_price_list describes. A list's currency cannot be changed once it is made: its prices are in it, and a currency naming a different one is refused with 422.

Delete a price list, its rules and every price row it holds. Prices go back to what the variant says the moment it is gone.

One variant's own quantity ladder — the "buy ten and save" breaks that belong to no price list and apply to every shopper. Each rung is a unit price at a quantity range, lowest rung first. A price list's rows beat these; these beat the variant's own price. Name the variant by variant_id or by sku. On a store that sells in more than one currency each currency has its own ladder, and currency says which one (the base currency when left out).

Replace one variant's quantity ladder. An empty tiers list removes it. Rungs may not overlap and a rung starts at 1 or more; leave the top rung's max_quantity out so it covers every larger order. A gap between rungs is allowed and means a quantity in the gap is priced by the variant's own price. Name the variant by variant_id or by sku. On a store that sells in more than one currency this replaces the ladder in one currency, named by currency (the base currency when left out), and leaves the ladders in the others standing. A variant with no ladder in a currency has no quantity breaks in it, and nothing is worked out from another currency's ladder.

Say what a bulk edit would do without doing any of it — how many products and variants it would touch, and the before and after of the first ten. Writes nothing at all. Same body as bulk_update_products.

Change price, compare price, stock quantity, status, visibility, featured or the quantity limits across many products in one transaction, using Change to / Increase by / Decrease by with a fixed amount or a percentage. Writes one history entry per product recording what changed from what to what. Stock changes go through the stock service so they fire the usual events. Refused past admin.bulk.max_rows rather than truncated. Preview it with preview_bulk_update first.

Read what has happened to one product — every bulk edit and every import that changed it, newest first, each carrying the fields that changed with their before and after values in minor units and the person who made the change. Useful for answering "why is this price different".

List what the CSV importer can import — the five entities (categories, products, variants, customers, orders) in the order a whole-store migration has to run them, the fields each accepts with their types and the column headings they are usually exported under, which keys rows can be matched on, and which fields are required. Fields contributed by add-on plugins are included. Call this before writing a mapping. In an orders file the currency field says which currency each order is in (the store's own when the cell is empty, or any currency the store sells in), and that row's amounts are read in it, so 1500 in a yen row is 1500 yen. A row in a currency the store does not sell in fails on its own.

List the saved column mappings, each with the entity it describes, the key rows are matched on, what it does with rows that already exist, and the column-to-field map itself. The same mappings the admin importer and bin/plugin kahunacart import --mapping= both use.

Save a reusable column mapping so the same export can be imported again next month without describing the file twice. columns maps each column heading in the file to one field name from list_import_fields; a heading you leave out or map to an empty string is ignored. The match key must be one of the columns, and every required field for the entity must be mapped.

Change a saved mapping. Anything you leave out keeps its stored value, so renaming one does not mean posting its whole column map back.

Delete a saved column mapping. Import runs that used it keep their own copy of the columns, so nothing already run or running is affected.

Rehearse an import of an already-uploaded file: the same writers, the same values, inside a transaction that is always rolled back. Answers what would be created, updated, skipped and failed, with each failure carrying the line number of the merchant's own file. Writes nothing at all — no rows, no run record. Give upload (the token a file upload answered with) and either mapping_id or an inline mapping. An orders row keeps its own currency, and a currency the store does not sell in is reported as that row's failure.

Queue an import of an already-uploaded file. The work happens in the background job queue a batch at a time, so read its progress with get_import_run. Nothing is ever deleted and the run is idempotent on the mapping's match key, so running the same file twice does what running it once does. Importing customers or orders needs the orders permission as well.

List recent import runs, newest first, with their entity, status, progress and counts of rows created, updated, skipped and failed.

Read one import run's progress and its first fifty failed rows, each with the line number of the merchant's own file and the reason it failed. The full error report is downloadable as a CSV from the admin.

Store a CSV and answer with its header row and a guess at each column