Price Lists

Organize the prices items sell at — into tiers like retail and wholesale, or cost structures — with volume pricing.

Overview

Price Lists organize the prices your items sell at. A price list is a tier — Retail, Wholesale, Distributor — or a cost structure, and a price links one item to one list at a specific value. The same item can carry different prices across lists, including volume pricing (quantity-based discounts). For the bigger picture, see the Commerce overview.

Pricing has three pieces:

• Item Codes — the SKU that bridges a product to commerce.
• Price Lists — the named tiers (or cost lists).
• Prices — an item’s value within a list.

Price List

Property	Type	Required	Description
title	string	Yes	Display name (for example Retail Prices).
slug	string	Yes	Identifier.
type	enum	Yes	price (customer-facing) or cost (internal).
is_default	boolean	No	Whether this is the default list for its type.
badge_color	string	No	A color for the list’s badge.

Two lists are special: the default price list and the default cost list. New orders pull an item’s selling price and cost from these by default.

Prices

A price links an item to a price list with a value:

Property	Type	Required	Description
item_code_id	reference	Yes	The item (SKU) being priced.
price_list_id	reference	Yes	The list this price belongs to.
price	number	Yes	The price value.
volume_prices	array	No	Quantity-based tiers — see below.

Volume pricing

A price can offer lower unit prices at higher quantities:

[
  { "quantity": 10, "price": 87.99 },
  { "quantity": 20, "price": 86.99 },
  { "quantity": 50, "price": 84.99 }
]

Each tier’s quantity must be a whole number greater than 1 and unique; tiers are sorted by quantity. The base price covers quantity 1.

Item Codes

An Item Code is the SKU that makes a product orderable, priceable, and trackable in inventory. It carries the item’s default price, standard cost, and a markup computed from the two.

• Markup is ((default price − standard cost) / standard cost) × 100, kept up to date whenever the price or cost changes.
• Item codes are created automatically when a product with item codes is configured — not through the API directly.
• The default price and cost stay in sync with the default price list and default cost list (change one and the other follows).

How prices reach an order

When you add a line item, its unit price defaults to the item’s price in the default price list (and its cost from the default cost list). You can override the unit price on the line, and the line’s discount, tax, and totals are calculated from there. See Orders.

Seeds

Price lists and prices aren’t currently supported in Seeds.

Governance & permissions

Only a super admin or Master can manage price lists and prices.

Related

Orders

Where prices become line-item amounts.

Inventory

Stock levels for the same items.