Order Totals - Spree Commerce documentation

Overview

An order total is rarely just the sum of the item prices. Tax is added or already inside them, a promo code takes something off, delivery costs something, gift wrapping costs a bit more. Spree records each of those as its own kind of row, and keeps a running total for each kind on the order itself. That means the summary block in your checkout is a handful of fields — you don’t add anything up yourself.

The totals

const order = await client.orders.get('or_xxx')

order.display_item_total     // "$120.00"  items, before tax and discounts
order.display_discount_total // "-$12.00"  everything taken off
order.display_delivery_total // "$5.00"    delivery
order.display_fee_total      // "$2.50"    surcharges
order.display_tax_total      // "$22.60"   all tax
order.display_total          // "$138.10"  what the customer pays

curl 'https://api.mystore.com/api/v3/store/orders/or_xxx' \
  -H 'X-Spree-API-Key: pk_xxx' \
  -H 'Authorization: Bearer $CUSTOMER_JWT'

Attribute	What it sums
`item_total`	Line item prices, before tax and discounts
`discount_total`	Every discount
`delivery_total`	Delivery charges
`fee_total`	Every fee
`tax_total`	All tax
`included_tax_total`	Tax already inside the displayed prices
`additional_tax_total`	Tax added on top
`total`	What the customer pays
`amount_due`	Still to pay, after gift cards and store credit

Two forms of every amount

Every total comes twice: total is the raw value, display_total is formatted for the order’s currency.

Response

{
  "total": "138.10",
  "display_total": "$138.10"
}

Render the display_ one. It knows the currency symbol, which side it goes on, and which separator that locale uses — $138.10, 138,10 €, ¥138. Formatting it yourself means reimplementing that, and getting it wrong for somebody.

Money is a string, never a number. JavaScript can’t represent every decimal exactly: 0.1 + 0.2 gives 0.30000000000000004, which is not something you want inside a price.If you must do arithmetic, use a decimal library or work in whole cents. Most of the time you don’t need to — Spree already did it.

The double-counting trap

If you build a subtotal yourself, include additional_tax_total only — never included_tax_total.Included tax is already inside the item prices. Adding it again charges the customer’s eyes twice, and produces a summary that doesn’t match the amount taken from their card. This is the single most common bug in a European storefront.

The two exist because the same order can carry both: VAT already inside the goods, and a separately-added tax on something else. tax_total covers both, which is why it’s the safe field to display on its own line.

Totals update themselves

Every change to a cart returns the whole cart, totals included:

const cart = await client.carts.items.create(cartId, {
  variant_id: 'var_xxx',
  quantity: 2,
})

cart.display_total // already correct

curl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_xxx/items' \
  -H 'X-Spree-API-Key: pk_xxx' \
  -H 'Content-Type: application/json' \
  -d '{ "variant_id": "variant_xxx", "quantity": 2 }'

There is never a second “recalculate” request to make, and never a moment where the summary on screen disagrees with what the server thinks. Adding an item, entering an address, applying a code — each response carries the new numbers. The totals are worked out again at the moment the cart is completed, so a price that changed while the customer sat on the review page can’t lead to the wrong charge.

Once an order is placed

The rows stop being regenerated. Editing a placed order re-adds the rows it already has rather than starting over, so today’s promotions and rates can’t rewrite what a customer agreed to last week.

Where each row attaches

The individual rows are there if you need them — an itemised invoice, a tax report:

Tax lines → a line item, a fulfillment, or a fee
Discounts → a line item or a fulfillment
Fees → a line item, a fulfillment, or the order itself

Each row also keeps a copy of where it came from — the rate and label on a tax line, the code and promotion on a discount. If someone deletes that promotion next month, the order still says what the customer was actually given.

Taxes — how tax is worked out
Discounts — money off
Fees — surcharges and duties
Carts — checkout and completion
Orders — the placed order

​Overview

​The totals

​Two forms of every amount

​The double-counting trap

​Totals update themselves

​Once an order is placed

​Where each row attaches

​Related

Overview

The totals

Two forms of every amount

The double-counting trap

Totals update themselves

Once an order is placed

Where each row attaches

Related