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.

Rename shipments to fulfillments in API documentation (#14007)

Damian Legawiec7f29a3d00d3a
diff --git a/docs/api-reference/webhooks-events.mdx b/docs/api-reference/webhooks-events.mdx
index 72b7e3d47d..37be556840 100644
--- a/docs/api-reference/webhooks-events.mdx
+++ b/docs/api-reference/webhooks-events.mdx
@@ -39,7 +39,7 @@ Event payloads include the same top-level attributes and unconditional associati
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
{
@@ -51,12 +51,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",
@@ -92,19 +92,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": [],
"..."
}
],
@@ -270,29 +271,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": []
}
```
@@ -450,7 +452,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"
diff --git a/docs/developer/core-concepts/adjustments.mdx b/docs/developer/core-concepts/adjustments.mdx
index 03e1c5e0df..c8a0161eb4 100644
--- a/docs/developer/core-concepts/adjustments.mdx
+++ b/docs/developer/core-concepts/adjustments.mdx
@@ -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:
<CodeGroup>
@@ -94,7 +94,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>'
```
diff --git a/docs/developer/core-concepts/events.mdx b/docs/developer/core-concepts/events.mdx
index 20bb4e1901..5a0fbcb70d 100644
--- a/docs/developer/core-concepts/events.mdx
+++ b/docs/developer/core-concepts/events.mdx
@@ -309,10 +309,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 |
diff --git a/docs/developer/core-concepts/orders.mdx b/docs/developer/core-concepts/orders.mdx
index 0782b75271..ea87a5b1e8 100644
--- a/docs/developer/core-concepts/orders.mdx
+++ b/docs/developer/core-concepts/orders.mdx
@@ -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"`).
@@ -182,10 +182,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)
@@ -217,12 +218,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' \
@@ -274,7 +275,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'],
})
```
@@ -284,7 +285,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>'
```
@@ -310,14 +311,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](/developer/core-concepts/shipments) and [Payments](/developer/core-concepts/payments).
diff --git a/docs/developer/core-concepts/payments.mdx b/docs/developer/core-concepts/payments.mdx
index 5e499ddef9..a97b251b9f 100644
--- a/docs/developer/core-concepts/payments.mdx
+++ b/docs/developer/core-concepts/payments.mdx
@@ -238,7 +238,7 @@ sequenceDiagram
**This step does NOT complete the order** — it only handles payment processing. For wallet payments (Apple Pay, Google Pay), the gateway also patches the order's billing address with data from the wallet at this stage.
</Step>
<Step title="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.
</Step>
diff --git a/docs/developer/core-concepts/shipments.mdx b/docs/developer/core-concepts/shipments.mdx
index 4d04cd84a7..253a36d533 100644
--- a/docs/developer/core-concepts/shipments.mdx
+++ b/docs/developer/core-concepts/shipments.mdx
@@ -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
@@ -83,35 +87,36 @@ During checkout, after the customer provides a shipping address, Spree calculate
<CodeGroup>
```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" }'
```
</CodeGroup>
diff --git a/docs/developer/core-concepts/webhooks.mdx b/docs/developer/core-concepts/webhooks.mdx
index ee30e3d9b0..068b682259 100644
--- a/docs/developer/core-concepts/webhooks.mdx
+++ b/docs/developer/core-concepts/webhooks.mdx
@@ -133,7 +133,7 @@ Each webhook delivery sends a JSON payload with the following structure. The `da
"item_count": 3,
"currency": "USD",
"items": [ ... ],
- "shipments": [ ... ],
+ "fulfillments": [ ... ],
"payments": [ ... ]
},
"metadata": {