@spree/docs 0.1.176 → 0.1.178

package/dist/developer/core-concepts/orders.md

@@ -1,409 +1,162 @@
 ---
 title: Orders
-description: How Spree models orders — the cart-to-completion lifecycle, checkout state machine, line items, payments, shipments, and order totals.
+description: How Spree models orders — a permanent record created by completing a cart, with separate payment and delivery statuses.
 ---
 
 ## Overview
 
-An order is the central model connecting a customer to their purchase. It collects line items, addresses, shipments, payments, and adjustments into a single transaction that flows through a checkout state machine from cart to completion.
+An order is a placed purchase. It's created by completing a [Cart](carts.md) and holds its own copy of everything the customer agreed to — items, prices, taxes, discounts and delivery.
 
 ```mermaid
 erDiagram
     Order ||--o{ LineItem : "has many"
-    Order ||--o{ Shipment : "has many"
+    Order ||--o{ Fulfillment : "has many"
     Order ||--o{ Payment : "has many"
-    Order ||--o{ Adjustment : "has many"
-    Order }o--|| Address : "ship_address"
-    Order }o--|| Address : "bill_address"
-    Order }o--|| User : "belongs to"
-    Order }o--|| Store : "belongs to"
-    LineItem }o--|| Variant : "belongs to"
-    Shipment }o--|| StockLocation : "ships from"
-    Payment }o--|| PaymentMethod : "belongs to"
+    Order ||--o{ Return : "has many"
+    Order }o--|| Cart : "created from"
+    Order }o--|| Customer : "belongs to"
 
     Order {
         string number
-        string state
-        string email
-        string currency
-        decimal total
-        string payment_state
-        string shipment_state
-    }
-
-    LineItem {
-        integer quantity
-        decimal price
-    }
-
-    Shipment {
-        string number
-        string state
-        string tracking
-    }
-
-    Payment {
-        decimal amount
-        string state
+        string payment_status
+        string fulfillment_status
+        string total
+        datetime completed_at
     }
 ```
 
-**Key relationships:**
-- **Line Items** link orders to [Variants](products.md#variants) (what was purchased)
-- **[Shipments](shipments.md)** handle fulfillment from stock locations
-- **[Payments](payments.md)** track payment attempts and their states
-- **[Adjustments](adjustments.md)** apply taxes, promotions, and shipping costs
-- **[Addresses](addresses.md)** store billing and shipping information
-
-## Order Attributes
-
-The API returns these key fields on every order:
+## Order attributes
 
 | Attribute | Description |
-|-----------|-------------|
-| `number` | Unique order number (e.g., `R123456789`), shown to customers |
+|---|---|
+| `id` | Order ID, e.g. `or_86Rf07xd4z` |
+| `number` | Order number shown to customers, e.g. `R1001` — sequential by default, [customizable](../how-to/custom-document-numbers.md) |
+| `cart_id` | The cart this order came from |
 | `email` | Customer's email address |
-| `currency` | Order currency (e.g., `USD`) |
+| `currency` | Order currency, e.g. `USD` |
 | `total_quantity` | Total number of items |
+| `payment_status` | See [statuses](#statuses) below |
+| `fulfillment_status` | See [statuses](#statuses) below |
 | `item_total` / `display_item_total` | Sum of line item prices |
 | `delivery_total` / `display_delivery_total` | Delivery cost |
 | `tax_total` / `display_tax_total` | Total tax |
-| `discount_total` / `display_discount_total` | Total discount from promotions |
-| `adjustment_total` / `display_adjustment_total` | Sum of all adjustments (tax + delivery + promos) |
-| `total` / `display_total` | Final order total |
-| `payment_status` | Payment status (`balance_due`, `paid`, `credit_owed`, `failed`, `void`) |
-| `fulfillment_status` | Fulfillment status (`pending`, `ready`, `partial`, `shipped`, `backorder`) |
-| `completed_at` | Timestamp when the order was placed |
-
-The [`display_*` fields return formatted strings with currency symbols](../../api-reference/store-api/monetary-amounts.md) (e.g., `"$15.99"`).
-
-## Cart
-
-A cart is simply an order in the `cart` state. Guest carts are [identified by a cart token; authenticated users' carts are linked to their account](../../api-reference/store-api/authentication.md).
-
-
-```typescript Store SDK
-// Create a cart
-const cart = await client.carts.create()
-// cart.token => "abc123" (save this for guest checkout)
-
-// Get existing cart
-const cart = await client.carts.get(cartId, { spreeToken: 'xxx' })
-
-// Add an item
-const updatedOrder = await client.carts.items.create(cart.id, {
-  variant_id: 'var_xxx',
-  quantity: 2,
-})
-
-// Update quantity
-await client.carts.items.update(cart.id, 'li_xxx', {
-  quantity: 3,
-})
-
-// Remove an item
-await client.carts.items.delete(cart.id, 'li_xxx')
-```
-
-```bash cURL
-# Create a cart
-curl -X POST 'https://api.mystore.com/api/v3/store/carts' \
-  -H 'X-Spree-API-Key: pk_xxx'
-
-# Get existing cart
-curl 'https://api.mystore.com/api/v3/store/carts/cart_xxx' \
-  -H 'X-Spree-API-Key: pk_xxx' \
-  -H 'X-Spree-Token: abc123'
-
-# Add an item
-curl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_xxx/items' \
-  -H 'X-Spree-API-Key: pk_xxx' \
-  -H 'X-Spree-Token: abc123' \
-  -H 'Content-Type: application/json' \
-  -d '{ "variant_id": "var_xxx", "quantity": 2 }'
-
-# Update quantity
-curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx/items/li_xxx' \
-  -H 'X-Spree-API-Key: pk_xxx' \
-  -H 'X-Spree-Token: abc123' \
-  -H 'Content-Type: application/json' \
-  -d '{ "quantity": 3 }'
-
-# Remove an item
-curl -X DELETE 'https://api.mystore.com/api/v3/store/carts/cart_xxx/items/li_xxx' \
-  -H 'X-Spree-API-Key: pk_xxx' \
-  -H 'X-Spree-Token: abc123'
-```
-
-
-Every item mutation returns the full updated order with recalculated totals.
-
-## Checkout Flow
-
-The checkout is a state machine that advances the order through a series of steps. Each step collects required information before allowing the order to proceed.
-
-**Step 1: cart**
-
-Customer has items in their cart. This is the starting state.
-
-  **Step 2: address**
+| `discount_total` / `display_discount_total` | Total discount |
+| `total` / `display_total` | Order total |
+| `amount_due` / `display_amount_due` | Still outstanding |
+| `completed_at` | When the order was placed |
 
-Customer provides shipping and billing addresses.
+Every amount comes in two forms: `total` is the raw value (`"135.60"`) and [`display_total` is formatted for the currency](../../api-reference/store-api/monetary-amounts.md) (`"$135.60"`). Render the `display_` one.
 
-  **Step 3: delivery**
+## Statuses
 
-Customer selects a shipping rate for each shipment.
+An order tracks payment and delivery separately, because they genuinely move at different speeds. An order can be paid but not yet sent, or sent and later partly refunded.
 
-  **Step 4: payment**
+**`payment_status`**
 
-Customer provides payment. Skipped if the order is fully covered by store credit.
+| Value | Meaning |
+|---|---|
+| `none` | Nothing paid or authorized yet |
+| `authorized` | Money is held but not taken |
+| `partially_paid` | Some of the total has been taken |
+| `paid` | Fully paid |
+| `partially_refunded` | Some money returned |
+| `refunded` | Everything returned |
+| `overcharged` | More was taken than the order total |
+| `voided` | The hold was released without taking money |
 
-  **Step 5: confirm**
+**`fulfillment_status`**
 
-Customer reviews and confirms the order.
+| Value | Meaning |
+|---|---|
+| `unfulfilled` | Nothing has gone out yet |
+| `backorder` | Waiting on stock |
+| `partial` | Some of it has gone out |
+| `fulfilled` | Everything has gone out |
+| `delivered` | The customer has all of it |
+| `canceled` | Nothing will be sent |
 
-  **Step 6: complete**
+A canceled parcel is ignored while others are still live, so an order whose second parcel was recalled is described by the first.
 
-Order is placed. `completed_at` is set and fulfillment begins.
+Both are worked out automatically from the order's payments, refunds and fulfillments. You change an order's status by acting on those — taking a payment, sending a parcel, issuing a refund — never by setting the status yourself.
 
+## Reading an order
 
-If the order doesn't meet the requirements for the next state (e.g., missing address), the API returns an error.
+A customer can fetch their own order; guests use the order token they got at checkout.
 
 
 ```typescript Store SDK
-// Set addresses
-await client.carts.update(cartId, {
-  email: 'john@example.com',
-  shipping_address: {
-    first_name: 'John', last_name: 'Doe',
-    address1: '123 Main St', city: 'Los Angeles',
-    country_iso: 'US', state_abbr: 'CA', postal_code: '90001',
-    phone: '555-0100',
-  },
-})
-
-// Get fulfillments and select a delivery rate
-// (the Store API/SDK exposes shipments as `fulfillments`)
-const cart = await client.carts.get(cartId)
-await client.carts.fulfillments.update(cartId, cart.fulfillments[0].id, {
-  selected_delivery_rate_id: 'rate_xxx',
-})
+// A single order
+const order = await client.orders.get('or_xxx')
 
-// Create a payment session (e.g., Stripe)
-const session = await client.carts.paymentSessions.create(cartId, {
-  payment_method_id: 'pm_xxx',
-})
-// session.external_data.client_secret => use with Stripe.js
-
-// Complete the payment session after provider confirmation
-await client.carts.paymentSessions.complete(cartId, session.id)
-
-// Complete the order
-await client.carts.complete(cartId)
+// The signed-in customer's order history
+const orders = await client.customers.orders.list({ per_page: 20 })
 ```
 
 ```bash cURL
-# Set addresses
-curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx' \
-  -H 'X-Spree-API-Key: pk_xxx' \
-  -H 'X-Spree-Token: abc123' \
-  -H 'Content-Type: application/json' \
-  -d '{
-    "email": "john@example.com",
-    "shipping_address": {
-      "first_name": "John", "last_name": "Doe",
-      "address1": "123 Main St", "city": "Los Angeles",
-      "country_iso": "US", "state_abbr": "CA", "postal_code": "90001",
-      "phone": "555-0100"
-    }
-  }'
-
-# Select a delivery rate
-curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx/fulfillments/ful_xxx' \
+curl 'https://api.mystore.com/api/v3/store/orders/or_xxx' \
   -H 'X-Spree-API-Key: pk_xxx' \
-  -H 'X-Spree-Token: abc123' \
-  -H 'Content-Type: application/json' \
-  -d '{ "selected_delivery_rate_id": "rate_xxx" }'
-
-# Complete the order
-curl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_xxx/complete' \
-  -H 'X-Spree-API-Key: pk_xxx' \
-  -H 'X-Spree-Token: abc123'
+  -H 'X-Spree-Token: order_token_xxx'
 ```
 
 
-## Coupon Codes
+## Managing orders
 
-Apply or remove promotional coupon codes during checkout:
+Back-office work happens through the Admin API.
 
 
-```typescript Store SDK
-// Apply a discount code
-await client.carts.discountCodes.apply(cartId, 'SAVE20')
-
-// Remove a discount code
-await client.carts.discountCodes.remove(cartId, 'SAVE20')
-```
-
-```bash cURL
-# Apply a discount code
-curl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_xxx/discount_codes' \
-  -H 'X-Spree-API-Key: pk_xxx' \
-  -H 'X-Spree-Token: abc123' \
-  -H 'Content-Type: application/json' \
-  -d '{ "code": "SAVE20" }'
-
-# Remove a discount code
-curl -X DELETE 'https://api.mystore.com/api/v3/store/carts/cart_xxx/discount_codes/SAVE20' \
-  -H 'X-Spree-API-Key: pk_xxx' \
-  -H 'X-Spree-Token: abc123'
-```
-
-
-## Order History
-
-Authenticated customers can view their past orders:
-
-
-```typescript Store SDK
-// List past orders
-const { data: orders } = await client.customer.orders.list()
-
-// Get a specific order with details
-const order = await client.orders.get('or_xxx', {
-  expand: ['items', 'fulfillments', 'payments'],
-})
-```
-
 ```typescript Admin SDK
-const order = await adminClient.orders.get('or_xxx')
-```
-
-```bash cURL
-# List past orders
-curl 'https://api.mystore.com/api/v3/store/customer/orders' \
-  -H 'Authorization: Bearer <jwt_token>'
-
-# Get a specific order
-curl 'https://api.mystore.com/api/v3/store/orders/or_xxx?expand=items,fulfillments,payments' \
-  -H 'Authorization: Bearer <jwt_token>'
-```
-
-
-## Managing Orders
-
-Everything above is the **Store API** — the customer's own cart and orders. Back-office order management (listing every order, creating phone/manual orders, capturing payments, cancelling) uses the [Admin API](../../api-reference/admin-api/introduction.md).
-
-### Listing and creating orders
-
-List orders with [Ransack filters and pagination](../../api-reference/admin-api/querying.md) (`state_eq`, `limit`, sorting). A draft order is created in one call; pass line items as `items` (each `{ variant_id, quantity }`):
-
-
-```typescript Admin SDK
-import { createAdminClient } from '@spree/admin-sdk'
-
-const client = createAdminClient({
-  baseUrl: 'https://store.example.com',
-  secretKey: 'sk_xxx',
+// Find orders needing attention
+const orders = await adminClient.orders.list({
+  filter: { payment_status_eq: 'paid', fulfillment_status_eq: 'unfulfilled' },
 })
 
-// List orders (Ransack filters)
-const { data: orders } = await client.orders.list({ state_eq: 'complete', limit: 25 })
-
-// Create a draft order on a customer's behalf
-const order = await client.orders.create({
-  email: 'buyer@example.com',
-  items: [{ variant_id: 'variant_xxx', quantity: 2 }],
-  currency: 'USD',
+// Cancel an order
+await adminClient.orders.cancel('or_xxx', {
+  reason: 'customer',
+  restock_items: true,
+  refund_payments: true,
 })
-```
 
-```bash CLI
-spree api get /orders -q state_eq=complete --limit 25
-spree api post /orders -d '{
-  "email": "buyer@example.com",
-  "items": [{ "variant_id": "variant_xxx", "quantity": 2 }]
-}'
-```
-
-
-### Order state actions
-
-Orders move through their [state machine](#checkout-flow) via dedicated actions rather than raw `state` writes:
+// Take an authorized payment
+await adminClient.orders.payments.capture('or_xxx', 'pay_xxx')
 
-
-```typescript Admin SDK
-await client.orders.complete('or_xxx')               // finalize a draft
-await client.orders.cancel('or_xxx', { reason: 'customer' })
-await client.orders.approve('or_xxx')
-await client.orders.resume('or_xxx')
-await client.orders.resendConfirmation('or_xxx')
-```
-
-```bash CLI
-spree api patch /orders/or_xxx/complete
-spree api patch /orders/or_xxx/cancel -d '{"reason": "customer"}'
-spree api patch /orders/or_xxx/approve
+// Refund against a specific payment
+await adminClient.orders.refunds.create('or_xxx', {
+  payment_id: 'pay_xxx',
+  amount: '25.00',
+})
 ```
 
+```bash cURL
+curl 'https://api.mystore.com/api/v3/admin/orders?filter[payment_status_eq]=paid' \
+  -H 'X-Spree-API-Key: sk_xxx'
 
-### Payments and refunds
-
-Capture or void an authorized payment, and issue refunds, through the nested order resources:
-
-
-```typescript Admin SDK
-await client.orders.payments.capture('or_xxx', 'pay_xxx')
-await client.orders.payments.void('or_xxx', 'pay_xxx')
-await client.orders.refunds.create('or_xxx', { payment_id: 'pay_xxx', amount: '19.99' })
-```
-
-```bash CLI
-spree api patch /orders/or_xxx/payments/pay_xxx/capture
-spree api post /orders/or_xxx/refunds -d '{"payment_id": "pay_xxx", "amount": "19.99"}'
+curl -X PATCH 'https://api.mystore.com/api/v3/admin/orders/or_xxx/cancel' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{ "reason": "customer", "restock_items": true }'
 ```
 
 
-## Line Items
-
-Line items represent individual products in an order. Each line item links to a [Variant](products.md#variants) and tracks the quantity and price at the time of purchase.
-
-When a variant is added to an order, the price is locked on the line item. If the variant's price changes later, existing orders are unaffected.
-
-## Adjustments
+Canceling records who canceled and why, puts stock back, and settles any payments.
 
-[Adjustments](adjustments.md) modify an order's total — promotions decrease it, taxes and shipping increase it. Adjustments can be applied at the order level, the line item level, or the shipment level.
+## Orders don't change quietly
 
-## Payment States
+A placed order is meant to stay put. Its items and prices are written when the cart is completed and then left alone, so an order keeps saying what the customer actually agreed to — even if a product's price changes the next day.
 
-| State | Description |
-|-------|-------------|
-| `balance_due` | Payment total is less than the order total |
-| `paid` | Payment total equals the order total |
-| `credit_owed` | Payment total exceeds the order total (refund pending) |
-| `failed` | Most recent payment attempt failed |
-| `void` | Order was canceled and payments voided |
+Where admin edits are allowed, totals are re-added from the order's existing rows rather than worked out again from scratch. Editing an order must never quietly re-apply today's promotions and hand the customer a different discount than the one they accepted.
 
-## Fulfillment Statuses
+## Money on an order
 
-The order's `fulfillment_status` field summarizes the state of all fulfillments (the Store API/SDK exposes shipments as `fulfillments`).
+Tax, discounts and fees are kept as separate records, so you can ask what tax was charged without picking through a mixed list. See [Taxes, Discounts & Fees](taxes-discounts-fees.md).
 
-| Status | Description |
-|--------|-------------|
-| `pending` | All fulfillments are pending |
-| `ready` | All fulfillments are ready to ship |
-| `partial` | At least one fulfillment is shipped, others are not |
-| `shipped` | All fulfillments have been shipped |
-| `backorder` | Some inventory is on backorder |
+## Events
 
-For more details, see [Shipments](shipments.md) and [Payments](payments.md).
+Orders publish [events](events.md) — `order.placed`, `order.canceled`, `order.paid` and more — which also reach [webhooks](webhooks.md). This is the right way to push orders to another system, trigger fulfillment, or start an email flow.
 
-## Related Documentation
+## Related
 
-- [Cart, Checkout & Orders](../sdk/store/cart-checkout.md) — Store SDK guide for carts, checkout, coupon codes, and order history
-- [Payments](payments.md) — Payment processing and payment sessions
-- [Shipments](shipments.md) — Fulfillment and shipping rates
-- [Addresses](addresses.md) — Billing and shipping addresses
-- [Promotions](promotions.md) — Discounts and coupon codes
-- [Checkout Customization](../customization/checkout.md) — Customizing the checkout flow
-- [Events](events.md) — Subscribe to order events (e.g., `order.completed`)
+- [Carts](carts.md) — shopping and checkout
+- [Fulfillments](fulfillments.md) — getting items to the customer
+- [Returns, Exchanges & Claims](returns-exchanges-claims.md) — after the sale
+- [Payments](payments.md) — payment methods and processing

package/dist/developer/core-concepts/payments.md

@@ -682,7 +682,7 @@ See [Events](events.md) for more details on subscribing to events.
 - [Payments (Store SDK)](../sdk/store/payments.md) - SDK how-to for payment sessions, payments, and setup sessions
 - [Build a Custom Payment Method](../how-to/custom-payment-method.md) - Step-by-step guide to creating your own payment gateway integration
 - [Orders](orders.md) - Order management and state machine
-- [Checkout Customization](../customization/checkout.md) - Customizing the checkout flow
+- [Checkout Customization](carts.md) - Customizing the checkout flow
 - [Events](events.md) - Subscribe to payment events
 
 ## Key Services