Adjustments

Overview

An Adjustment modifies the price of an Order, a Line Item, or a Shipment. Adjustments can be positive (charges) or negative (credits).

mermaid

erDiagram
    Adjustment {
        decimal amount
        string label
        boolean eligible
        boolean mandatory
        string state
        boolean included
        string source_type
        string adjustable_type
    }

    Order ||--o{ Adjustment : "has many"
    Order ||--o{ LineItem : "has many"
    Order ||--o{ Shipment : "has many"
    LineItem ||--o{ Adjustment : "has many"
    Shipment ||--o{ Adjustment : "has many"
    TaxRate ||--o{ Adjustment : "creates"
    PromotionAction ||--o{ Adjustment : "creates"

Key relationships:

Adjustment modifies prices on orders, line items, or shipments
Source is where the adjustment comes from (Tax Rate or Promotion Action)
Adjustable is what's being adjusted (Order, LineItem, or Shipment)
Positive amounts are charges, negative amounts are credits

Adjustment Types

Included vs Additional

Included adjustments are part of the item's displayed price (e.g., VAT in European stores)
Additional adjustments are added on top of the item's price (e.g., US sales tax)

Sources

Adjustments are created by two sources:

Source	Example	Typical Amount
Tax Rate	Sales tax, VAT	Positive (charge)
Promotion Action	Coupon discount, free shipping	Negative (credit)

Adjustment Attributes

Attribute	Description	Example
`amount`	The monetary value of the adjustment	`-10.00`
`label`	Human-readable description	`10% off order`
`eligible`	Whether the adjustment currently applies	`true`
`mandatory`	If `true`, always applied regardless of eligibility rules	`false`
`state`	`open` (auto-updated) or `closed` (locked)	`open`
`included`	Whether the amount is included in the item's displayed price	`false`

Adjustment Lifecycle

Open adjustments are recalculated whenever the order is updated (e.g., items added/removed, address changed)
Closed adjustments are locked and will not be automatically recalculated
When a promotion becomes ineligible (e.g., item removed from cart), its adjustments are automatically removed

Store API

Adjustments appear in order responses when you expand line items or shipments:

typescript

const order = await client.orders.get('or_abc123', {
  spreeToken: '<token>',
})

// Line item adjustments (promotions, taxes)
order.items?.forEach(item => {
  item.adjustment_total  // total adjustments on this item
  item.additional_tax_total
  item.included_tax_total
})

// Order-level totals
order.adjustment_total    // total of all adjustments
order.promo_total         // total promotional discounts
order.additional_tax_total
order.included_tax_total

bash

curl 'https://api.mystore.com/api/v3/store/orders/or_abc123?expand=items,shipments' \
  -H 'Authorization: Bearer pk_xxx' \
  -H 'X-Spree-Token: <token>'

</CodeGroup>

Promotions — Promotion-based adjustments
Taxes — Tax adjustments
Shipments — Shipping adjustments
Orders — How adjustments affect order totals