Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

4.4 KB
Raw Blame
---
title: Adjustments
description: How Spree adjustments apply taxes, promotions, and other price modifications to orders, line items, and shipments, and how totals are recalculated.
canonical: "https://spreecommerce.org/docs/v5/developer/core-concepts/adjustments"
---

## Overview

An Adjustment modifies the price of an [Order](/v5/developer/core-concepts/orders), a [Line Item](/v5/developer/core-concepts/orders#line-items), or a [Shipment](/v5/developer/core-concepts/shipments). 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](/v5/developer/core-concepts/taxes) or [Promotion Action](/v5/developer/core-concepts/promotions))
- **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](/v5/developer/core-concepts/taxes) | Sales tax, VAT | Positive (charge) |
| [Promotion Action](/v5/developer/core-concepts/promotions) | 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=items,fulfillments`](/api-reference/store-api/relations) on the order. The response exposes the [`amount`, `adjustment_total`, and the tax totals](/api-reference/store-api/monetary-amounts) as money fields:

<CodeGroup>

```typescript Store SDK
const order = await client.orders.get('or_abc123', { expand: ['items', 'fulfillments'] }, {
  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.discount_total         // total promotional discounts
order.display_discount_total // formatted promotional discounts
order.additional_tax_total
order.included_tax_total
```

```typescript Admin SDK
const order = await adminClient.orders.get('or_abc123')
```

```bash cURL
curl 'https://api.mystore.com/api/v3/store/orders/or_abc123?expand=items,fulfillments' \
  -H 'X-Spree-API-Key: pk_xxx' \
  -H 'X-Spree-Token: <token>'
```

</CodeGroup>

## Related Documentation

- [Promotions](/v5/developer/core-concepts/promotions) — Promotion-based adjustments
- [Taxes](/v5/developer/core-concepts/taxes) — Tax adjustments
- [Shipments](/v5/developer/core-concepts/shipments) — Shipping adjustments
- [Orders](/v5/developer/core-concepts/orders) — How adjustments affect order totals
- [Calculators](/v5/developer/core-concepts/calculators) — How tax rate and promotion action amounts are computed