@spree/docs 0.1.46 → 0.1.47

package/dist/api-reference/webhooks-events.md

@@ -37,7 +37,7 @@ For details on creating webhook endpoints and verifying signatures, see [Webhook
 
 Events: `order.created`, `order.updated`, `order.completed`, `order.canceled`, `order.resumed`, `order.paid`, `order.shipped`
 
-Order payloads include nested `items`, `shipments`, `payments`, `bill_address`, `ship_address`, `payment_methods`, and `promotions`.
+Order payloads include nested `items`, `fulfillments` (the Store API name for shipments), `payments`, `billing_address`, `shipping_address`, `payment_methods`, and `discounts`.
 
 ```json
 {
@@ -49,12 +49,12 @@ Order payloads include nested `items`, `shipments`, `payments`, `bill_address`,
   "special_instructions": null,
   "currency": "USD",
   "item_count": 3,
-  "shipment_state": "shipped",
+  "fulfillment_status": "shipped",
   "payment_state": "paid",
   "item_total": "89.99",
   "display_item_total": "$89.99",
-  "ship_total": "10.00",
-  "display_ship_total": "$10.00",
+  "delivery_total": "10.00",
+  "display_delivery_total": "$10.00",
   "adjustment_total": "0.00",
   "display_adjustment_total": "$0.00",
   "promo_total": "0.00",
@@ -90,19 +90,20 @@ Order payloads include nested `items`, `shipments`, `payments`, `bill_address`,
       "..."
     }
   ],
-  "shipments": [
+  "fulfillments": [
     {
-      "id": "shp_9xPq4wMn",
+      "id": "ful_9xPq4wMn",
       "number": "H123456789",
-      "state": "shipped",
+      "status": "shipped",
+      "fulfillment_type": "shipping",
       "tracking": "1Z999AA10123456784",
       "tracking_url": "https://tools.usps.com/go/TrackConfirmAction?tLabels=1Z999AA10123456784",
       "cost": "10.00",
       "display_cost": "$10.00",
-      "shipped_at": "2025-01-16T14:00:00Z",
-      "shipping_method": { "id": "sm_2wMn7xRt", "..." },
+      "fulfilled_at": "2025-01-16T14:00:00Z",
+      "delivery_method": { "id": "dm_2wMn7xRt", "..." },
       "stock_location": { "id": "sl_2wMn7xRt", "..." },
-      "shipping_rates": [],
+      "delivery_rates": [],
       "..."
     }
   ],
@@ -268,29 +269,30 @@ Payment setup session payloads include a nested `payment_method`.
 
 Events: `shipment.created`, `shipment.updated`, `shipment.shipped`, `shipment.canceled`, `shipment.resumed`
 
-Shipment payloads include nested `shipping_method`, `stock_location`, and `shipping_rates`.
+The Store API/SDK exposes shipments as `fulfillments`, and webhook payloads use the same V3 serializer. Payloads include nested `delivery_method`, `stock_location`, and `delivery_rates`.
 
 ```json
 {
-  "id": "shp_9xPq4wMn",
+  "id": "ful_9xPq4wMn",
   "number": "H123456789",
-  "state": "shipped",
+  "status": "shipped",
+  "fulfillment_type": "shipping",
   "tracking": "1Z999AA10123456784",
   "tracking_url": "https://tools.usps.com/go/TrackConfirmAction?tLabels=1Z999AA10123456784",
   "cost": "10.00",
   "display_cost": "$10.00",
-  "shipped_at": "2025-01-16T14:00:00Z",
+  "fulfilled_at": "2025-01-16T14:00:00Z",
   "created_at": "2025-01-15T10:30:00Z",
   "updated_at": "2025-01-16T14:00:00Z",
-  "shipping_method": {
-    "id": "sm_2wMn7xRt",
+  "delivery_method": {
+    "id": "dm_2wMn7xRt",
     "..."
   },
   "stock_location": {
     "id": "sl_2wMn7xRt",
     "..."
   },
-  "shipping_rates": []
+  "delivery_rates": []
 }
 ```
 
@@ -448,7 +450,7 @@ Events: `stock_movement.created`, `stock_movement.updated`, `stock_movement.dele
   "quantity": -1,
   "action": "sold",
   "originator_type": "Spree::Shipment",
-  "originator_id": "shp_9xPq4wMn",
+  "originator_id": "ful_9xPq4wMn",
   "stock_item_id": "si_6nRt2xLq",
   "created_at": "2025-01-15T10:30:00Z",
   "updated_at": "2025-01-15T10:30:00Z"

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

@@ -70,7 +70,7 @@ Adjustments are created by two sources:
 
 ## Store API
 
-Adjustments appear in order responses when you expand line items or shipments:
+Adjustments appear in order responses when you expand line items or fulfillments:
 
 
 ```typescript SDK
@@ -93,7 +93,7 @@ order.included_tax_total
 ```
 
 ```bash cURL
-curl 'https://api.mystore.com/api/v3/store/orders/or_abc123?expand=items,shipments' \
+curl 'https://api.mystore.com/api/v3/store/orders/or_abc123?expand=items,fulfillments' \
   -H 'Authorization: Bearer pk_xxx' \
   -H 'X-Spree-Token: <token>'
 ```

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

@@ -306,10 +306,10 @@ Spree includes V3 serializers for all core models in [`api/app/serializers/spree
 
 | Serializer | Model |
 |------------|-------|
-| `OrderSerializer` | Orders with totals, states, nested line items, shipments, payments, addresses |
+| `OrderSerializer` | Orders with totals, statuses, nested line items, fulfillments, payments, addresses |
 | `ProductSerializer` | Products with pricing, stock status, availability |
 | `PaymentSerializer` | Payments with amounts, states, nested payment method and source |
-| `ShipmentSerializer` | Shipments with tracking, nested shipping method and rates |
+| `FulfillmentSerializer` | Fulfillments (shipments) with tracking, nested delivery method and delivery rates |
 | `LineItemSerializer` | Line items with quantity, pricing, nested option values |
 | `VariantSerializer` | Variants with SKU, pricing, nested option values |
 | `PriceSerializer` | Prices with amounts, currency, price list |

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

@@ -67,13 +67,13 @@ The API returns these key fields on every order:
 | `currency` | Order currency (e.g., `USD`) |
 | `item_count` | Total number of items |
 | `item_total` / `display_item_total` | Sum of line item prices |
-| `ship_total` / `display_ship_total` | Shipping cost |
+| `delivery_total` / `display_delivery_total` | Delivery cost |
 | `tax_total` / `display_tax_total` | Total tax |
 | `promo_total` / `display_promo_total` | Total discount from promotions |
-| `adjustment_total` / `display_adjustment_total` | Sum of all adjustments (tax + shipping + promos) |
+| `adjustment_total` / `display_adjustment_total` | Sum of all adjustments (tax + delivery + promos) |
 | `total` / `display_total` | Final order total |
 | `payment_state` | Payment status (`balance_due`, `paid`, `credit_owed`, `failed`, `void`) |
-| `shipment_state` | Shipment status (`pending`, `ready`, `partial`, `shipped`, `backorder`) |
+| `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 (e.g., `"$15.99"`).
@@ -183,10 +183,11 @@ await client.carts.update(cartId, {
   },
 })
 
-// Get shipments and select a shipping rate
-const { data: shipments } = await client.carts.shipments.list(cartId)
-await client.carts.shipments.update(cartId, shipments[0].id, {
-  selected_shipping_rate_id: 'sr_xxx',
+// Get fulfillments and select a delivery rate
+// (the Store API/SDK exposes shipments as `fulfillments`)
+const cart = await client.carts.get(cartId, { expand: ['fulfillments'] })
+await client.carts.fulfillments.update(cartId, cart.fulfillments[0].id, {
+  selected_delivery_rate_id: 'rate_xxx',
 })
 
 // Create a payment session (e.g., Stripe)
@@ -218,12 +219,12 @@ curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx' \
     }
   }'
 
-# Select a shipping rate
-curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx/shipments/shp_xxx' \
+# Select a delivery rate
+curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx/fulfillments/ful_xxx' \
   -H 'Authorization: Bearer pk_xxx' \
   -H 'X-Spree-Token: abc123' \
   -H 'Content-Type: application/json' \
-  -d '{ "selected_shipping_rate_id": "sr_xxx" }'
+  -d '{ "selected_delivery_rate_id": "rate_xxx" }'
 
 # Complete the order
 curl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_xxx/complete' \
@@ -271,7 +272,7 @@ const { data: orders } = await client.customer.orders.list()
 
 // Get a specific order with details
 const order = await client.orders.get('or_xxx', {
-  expand: ['items', 'shipments', 'payments'],
+  expand: ['items', 'fulfillments', 'payments'],
 })
 ```
 
@@ -281,7 +282,7 @@ 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,shipments,payments' \
+curl 'https://api.mystore.com/api/v3/store/orders/or_xxx?expand=items,fulfillments,payments' \
   -H 'Authorization: Bearer <jwt_token>'
 ```
 
@@ -306,14 +307,16 @@ When a variant is added to an order, the price is locked on the line item. If th
 | `failed` | Most recent payment attempt failed |
 | `void` | Order was canceled and payments voided |
 
-## Shipment States
+## Fulfillment Statuses
 
-| State | Description |
-|-------|-------------|
-| `pending` | All shipments are pending |
-| `ready` | All shipments are ready to ship |
-| `partial` | At least one shipment is shipped, others are not |
-| `shipped` | All shipments have been shipped |
+The order's `fulfillment_status` field summarizes the state of all fulfillments (the Store API/SDK exposes shipments as `fulfillments`).
+
+| 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 |
 
 For more details, see [Shipments](shipments.md) and [Payments](payments.md).

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

@@ -237,7 +237,7 @@ After the customer completes payment, the frontend calls the Complete Payment Se
 
   **Step 4: Complete Order**
 
-The frontend calls `POST /carts/:id/complete` to finalize the order. Spree validates the order is ready (addresses, shipments, payment), advances through any remaining checkout states, and marks the order as complete.
+The frontend calls `POST /carts/:id/complete` to finalize the order. Spree validates the order is ready (addresses, fulfillments, payment), advances through any remaining checkout states, and marks the order as complete.
 
     This separation ensures the same flow works for all payment types — inline cards, offsite redirects, and wallet payments.
 

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

@@ -49,15 +49,19 @@ erDiagram
 
 ## Shipment Attributes
 
+The Store API/SDK exposes shipments as `fulfillments` with these attributes:
+
 | Attribute | Description | Example |
 |-----------|-------------|---------|
-| `number` | Unique shipment identifier | `H12345678901` |
+| `number` | Unique fulfillment identifier | `H12345678901` |
 | `tracking` | Carrier tracking number | `1Z999AA10123456784` |
-| `state` | Current shipment state | `shipped` |
-| `cost` | Shipping cost | `9.99` |
-| `shipped_at` | When the shipment was shipped | `2025-07-21T14:36:00Z` |
+| `status` | Current fulfillment status | `shipped` |
+| `fulfillment_type` | `shipping` or `digital` | `shipping` |
+| `cost` | Delivery cost | `9.99` |
+| `fulfilled_at` | When the fulfillment was shipped | `2025-07-21T14:36:00Z` |
 | `stock_location` | Where items ship from | `Warehouse NYC` |
-| `selected_shipping_rate` | The rate chosen by the customer | `{ cost: 9.99, name: "UPS Ground" }` |
+| `delivery_method` | The selected delivery method | `{ id: "dm_xxx", name: "UPS Ground" }` |
+| `delivery_rates` | Available rates for the customer to pick from | `[{ id: "rate_xxx", cost: "9.99", selected: true, ... }]` |
 
 ## Shipment States
 
@@ -84,35 +88,36 @@ During checkout, after the customer provides a shipping address, Spree calculate
 
 
 ```typescript SDK
-// Get shipments with available shipping rates
+// Get fulfillments with available delivery rates
+// (the Store API/SDK exposes shipments as `fulfillments`)
 const order = await client.orders.get(orderId, {
-  expand: ['shipments'],
+  expand: ['fulfillments'],
 })
 
-// Each shipment has available shipping rates
-order.shipments?.forEach(shipment => {
-  console.log(shipment.number)           // "H12345678901"
-  console.log(shipment.shipping_rates)   // [{ id: "sr_xxx", name: "UPS Ground", cost: "9.99", selected: true }, ...]
+// Each fulfillment has available delivery rates
+order.fulfillments?.forEach(fulfillment => {
+  console.log(fulfillment.number)         // "H12345678901"
+  console.log(fulfillment.delivery_rates) // [{ id: "rate_xxx", name: "UPS Ground", cost: "9.99", selected: true }, ...]
 })
 
-// Select a shipping rate
-await client.carts.shipments.update(cartId, shipment.id, {
-  selected_shipping_rate_id: 'sr_xxx',
+// Select a delivery rate
+await client.carts.fulfillments.update(cartId, fulfillment.id, {
+  selected_delivery_rate_id: 'rate_xxx',
 })
 ```
 
 ```bash cURL
-# Get shipments
-curl 'https://api.mystore.com/api/v3/store/carts/cart_xxx?expand=shipments' \
+# Get fulfillments
+curl 'https://api.mystore.com/api/v3/store/carts/cart_xxx?expand=fulfillments' \
   -H 'Authorization: Bearer pk_xxx' \
   -H 'X-Spree-Token: abc123'
 
-# Select a shipping rate
-curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx/shipments/shp_xxx' \
+# Select a delivery rate
+curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx/fulfillments/ful_xxx' \
   -H 'Authorization: Bearer pk_xxx' \
   -H 'X-Spree-Token: abc123' \
   -H 'Content-Type: application/json' \
-  -d '{ "selected_shipping_rate_id": "sr_xxx" }'
+  -d '{ "selected_delivery_rate_id": "rate_xxx" }'
 ```
 
 

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

@@ -132,7 +132,7 @@ Each webhook delivery sends a JSON payload with the following structure. The `da
     "item_count": 3,
     "currency": "USD",
     "items": [ ... ],
-    "shipments": [ ... ],
+    "fulfillments": [ ... ],
     "payments": [ ... ]
   },
   "metadata": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spree/docs",
-  "version": "0.1.46",
+  "version": "0.1.47",
   "description": "Spree Commerce developer documentation for AI agents and local reference",
   "type": "module",
   "license": "CC-BY-4.0",