Understanding pricing layers
Propeller has a multi-layered pricing model. Understanding how prices are structured helps you display the right data in product listings, detail pages and carts.
Price types
Every product has several price fields:
| Field | Description |
|---|---|
gross | Price excluding tax |
net | Price including tax |
list | Default sales price, used as the baseline for discount calculations |
store | Price at which the product is sold at physical counter locations (common in building supplies, electrical wholesale and industrial parts distribution where the online price and counter price may differ) |
suggested | Manufacturer's or supplier's recommended retail price (RRP) |
cost | Purchase/cost price (deprecated in favor of costPrices) |
costPrices | Quantity-based cost prices with a quantityFrom threshold and value per unit |
The gross and net values are the ones customers actually pay. The other price types are reference prices useful for showing savings or comparing prices.
Propeller uses gross and net differently from standard accounting. In most accounting contexts, "gross" means including tax and "net" means excluding tax. Propeller uses it the other way around: gross is the price excluding tax and net is the price including tax.
The price field returns the calculated price for the current context (user, tax zone, quantity). The priceData field returns the raw price configuration.
Price source types
The price.type field tells you where the price came from:
| Type | Description |
|---|---|
DEFAULT | Standard product price (list price) |
PRICESHEET | Customer-specific price from a price sheet |
BULK_SALES_PRICE | Bulk/volume discount on the sales price |
BULK_COST_PRICE | Bulk/volume discount based on cost price |
Use this field to show context in your frontend, for example displaying a "Your price" label when type is PRICESHEET.
Discount calculation types
The price.discountType and priceData.bulkPriceDiscountType fields indicate how discounts are calculated. Propeller supports three calculation methods:
| Type | Description | Example |
|---|---|---|
COST_PRICE_PLUS | Cost price plus a percentage margin | Cost €40 + 25% = €50 |
LIST_PRICE_MIN | List price minus a percentage | List €100 − 20% = €80 |
NET_PRICE | Fixed amount (direct price) | Price = €75 |
Tax zones
Prices vary by tax zone. Pass a taxZone to the price query to get the correct tax calculation for the customer's region. The priceData.defaultTaxCode indicates the product's default tax rate (H = high, L = low, N = none).
How prices are resolved
When a product price is requested, Propeller evaluates pricing rules in this order:
- Customer-specific pricing (price sheets) always takes precedence over product-level pricing when the user is authenticated and has applicable price sheets, even if product-level pricing would produce a lower price
- Within price sheets, lower priority numbers take precedence
- When multiple price sheets have the same priority, the lowest price is selected
- When multiple discounts overlap in date range, the lowest price is selected
- If no price sheet applies, product-level bulk pricing is evaluated
- Orders outside configured volume ranges fall back to the list price
- When no pricing rules apply, the product's list price is used
Price sheets take precedence by design because customer-specific pricing in B2B represents a negotiated contract. A contract price governs the relationship even when a temporary product-level promotion would produce a lower price.
This resolution happens server-side. Your frontend always receives the final calculated price.
Price discounts
The price.discount field shows any discounts that apply to the product for the current user:
| Field | Description |
|---|---|
value | Discount amount or percentage |
quantityFrom | Minimum quantity to trigger the discount |
validFrom / validTo | Discount validity period |
Discounts can come from price sheets or bulk pricing. See Customer-specific pricing for details.
Surcharges
Surcharges are additional fees on top of the base price (handling fees, environmental charges, etc.).
| Field | Description |
|---|---|
type | Surcharge type: FlatFee (fixed amount) or Percentage |
value | The surcharge amount |
enabled | Whether the surcharge is currently active |
validFrom / validTo | Time window when the surcharge applies |
Cart pricing
When products are added to a cart, Propeller recalculates all prices server-side, applying:
- Customer-specific pricing (price sheets)
- Quantity-based discounts (bulk pricing)
- Action codes (discount codes)
- Shipping costs
- Transaction fees
- Tax calculations
You don't need to calculate anything in your frontend. All totals are returned by the cart query. See Cart management for details on cart totals.
Next steps
- Customer-specific pricing — price sheets, action codes and custom price overrides
- Tiered and volume pricing — bulk pricing and quantity discounts
- Cart management — how prices flow into the cart