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.

Document consignments, shipping labels and return labels

Damian Legawiec9cd2d2b3d23e
diff --git a/docs/developer/core-concepts/fulfillments.mdx b/docs/developer/core-concepts/fulfillments.mdx
index 86b5e3b308..896538b26c 100644
--- a/docs/developer/core-concepts/fulfillments.mdx
+++ b/docs/developer/core-concepts/fulfillments.mdx
@@ -14,6 +14,9 @@ erDiagram
Order ||--o{ Fulfillment : "has many"
Fulfillment ||--o{ FulfillmentItem : "has many"
Fulfillment ||--o{ DeliveryRate : "offers"
+ Fulfillment ||--o{ Delivery : "travels as"
+ Fulfillment ||--o{ ShippingLabel : "buys"
+ ShippingLabel ||--o| Delivery : "mints"
Fulfillment }o--|| StockLocation : "sourced from"
DeliveryRate }o--|| DeliveryMethod : "priced by"
DeliveryMethod }o--o{ DeliveryZone : "serves"
@@ -24,6 +27,19 @@ erDiagram
string tracking
string cost
datetime fulfilled_at
+ datetime delivered_at
+ }
+ Delivery {
+ string tracking_number
+ string carrier
+ string status
+ datetime delivered_at
+ }
+ ShippingLabel {
+ string source
+ string status
+ string cost
+ string tracking_number
}
```
@@ -34,11 +50,14 @@ erDiagram
| `id` | Fulfillment ID, e.g. `ful_86Rf07xd4z` |
| `number` | Fulfillment number, e.g. `F123456789` |
| `status` | See [statuses](#statuses) below |
-| `tracking` | Carrier tracking number, once it's on its way |
+| `tracking` / `tracking_url` | The first consignment's tracking number and link, summarised for convenience |
+| `deliveries` | Every consignment this batch travels as — see [consignments](#where-the-parcel-actually-is) |
+| `labels` | Postage bought or uploaded for it |
| `cost` / `display_cost` | Delivery cost for this fulfillment |
| `delivery_rates` | The options the customer can choose from |
| `selected_delivery_rate_id` | The chosen option |
| `fulfilled_at` | When it went out |
+| `delivered_at` | When the customer got it — what return windows count from |
## Statuses
@@ -57,7 +76,12 @@ Whether a fulfillment *can* go out — the order is paid, nothing is on backorde
### Where the parcel actually is
-Carrier reports live on a second field, `tracking_status`, and never change `status`:
+One fulfillment can travel as several parcels — a gym machine that arrives in
+three boxes, or a pallet moving under one freight PRO number. Each is a
+**delivery**: its own tracking number, its own carrier, its own journey.
+
+A delivery's `status` is what the carrier reports, and it never changes the
+fulfillment's own `status`:
| Value | Meaning |
|---|---|
@@ -70,11 +94,109 @@ Carrier reports live on a second field, `tracking_status`, and never change `sta
| `failure` | Delivery failed — a bad address, damage, a refused parcel |
| `unknown` | The carrier said something we don't recognise |
-Keeping the two apart is the point. A parcel that bounces still shows `fulfilled`, because you did hand it over; the trouble shows up as `return_to_sender` and you decide what to do about it. The one report that crosses over is delivery, which also sets `delivered` and `delivered_at`.
+Keeping the two apart is the point. A parcel that bounces still shows
+`fulfilled`, because you did hand it over; the trouble shows up as
+`return_to_sender` on that delivery and you decide what to do about it.
+
+The fulfillment rolls up from its deliveries: it becomes `delivered` when
+**every** consignment has arrived, so a machine that arrives in three boxes is
+only delivered when the third one lands. That rollup is recomputed whenever
+deliveries are added, removed or corrected — including when a tracking number
+is fixed, which starts that consignment's journey over.
+
+`delivered_at` is what return windows and the EU withdrawal period count from,
+so it records when the carrier says the parcel arrived rather than when you
+heard about it.
+
+Carriers report this through their provider's webhook, matched to the delivery
+by tracking number. With no carrier integration, staff mark receipt by hand —
+`markDelivered` in the Admin SDK, on a single delivery or the whole
+fulfillment — which is also how pickup orders get closed out.
+
+A fulfillment keeps `tracking` and `tracking_url` as a summary of its first
+consignment, so a storefront showing one tracking link needs no changes.
+
+<CodeGroup>
-`delivered_at` is what return windows and the EU withdrawal period count from, so it records when the carrier says the parcel arrived rather than when you heard about it.
+```typescript Admin SDK
+// Add a second parcel to the same fulfillment
+await adminClient.orders.fulfillments.deliveries.create('or_xxx', 'ful_xxx', {
+ tracking_number: '1Z999AA10123456784',
+})
+
+// Correct a number — the consignment's journey starts over
+await adminClient.orders.fulfillments.deliveries.update('or_xxx', 'ful_xxx', 'dlv_xxx', {
+ tracking_number: '9400100000000000000000',
+})
+
+// Confirm one parcel arrived
+await adminClient.orders.fulfillments.deliveries.markDelivered('or_xxx', 'ful_xxx', 'dlv_xxx')
+```
+
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/admin/orders/or_xxx/fulfillments/ful_xxx/deliveries' \
+ -H 'X-Spree-API-Key: sk_xxx' \
+ -H 'Content-Type: application/json' \
+ -d '{ "tracking_number": "1Z999AA10123456784" }'
+```
+
+</CodeGroup>
+
+## Shipping labels
+
+Postage is its own record. A label is either **purchased** through a carrier
+integration or **uploaded** — bought elsewhere and recorded so the PDF and its
+cost live with the consignment.
+
+Buying one mints the delivery it covers, so you never enter the tracking number
+yourself. The file is fetched into Spree's own storage right after purchase, so
+a merchant can reprint after the carrier's link has expired or the integration
+has been disconnected.
+
+A label's `cost` is what **you** paid the carrier. It is admin-only accounting
+data and never appears in a store API response or on the customer's order.
+
+| Field | Meaning |
+|---|---|
+| `source` | `purchased` or `uploaded` |
+| `status` | `purchased`, `refund_requested` or `refunded` |
+| `cost` / `currency` | What the merchant paid the carrier |
+| `tracking_number` | Frozen once bought |
+| `download_url` | Streamed through the API, never served from storage |
+
+A purchased label is given back by refunding it with the carrier; an uploaded
+one has nothing to refund, so it is deleted instead. Either way the consignment
+it minted goes with it only while the parcel never moved — once it is on its
+way, that journey is a fact and stays.
+
+<CodeGroup>
+
+```typescript Admin SDK
+// Buy postage through the carrier integration
+const label = await adminClient.orders.fulfillments.labels.create('or_xxx', 'ful_xxx')
+
+// Or record one bought elsewhere
+await adminClient.orders.fulfillments.labels.create('or_xxx', 'ful_xxx', {
+ file: signedBlobId,
+ tracking_number: '1Z999AA10123456784',
+ cost: '12.50',
+ currency: 'USD',
+})
+
+// Give the postage back
+await adminClient.orders.fulfillments.labels.refund('or_xxx', 'ful_xxx', label.id)
+```
+
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/admin/orders/or_xxx/fulfillments/ful_xxx/labels' \
+ -H 'X-Spree-API-Key: sk_xxx'
+```
+
+</CodeGroup>
-Carriers set this through their provider's webhook. With no carrier integration, staff mark receipt by hand — `markDelivered` in the Admin SDK — which is also how pickup orders get closed out.
+Some carriers also produce paperwork beside the label — a commercial invoice or
+a customs declaration for anything crossing a border. Those come back on the
+fulfillment's `documents`, each with a `kind` and a `url`.
## Delivery types
@@ -151,7 +273,9 @@ curl 'https://api.mystore.com/api/v3/store/delivery_methods/dm_xxx/pickup_locati
// What's still with you
const fulfillments = await adminClient.orders.fulfillments.list('or_xxx')
-// Add tracking, then mark it sent
+// Add tracking, then mark it sent. `tracking` is a shortcut that creates or
+// corrects the fulfillment's first consignment; use the deliveries endpoints
+// when a batch travels as more than one parcel.
await adminClient.orders.fulfillments.update('or_xxx', 'ful_xxx', {
tracking: '1Z999AA10123456784',
})
diff --git a/docs/developer/core-concepts/orders.mdx b/docs/developer/core-concepts/orders.mdx
index 587eb9d034..a89176775c 100644
--- a/docs/developer/core-concepts/orders.mdx
+++ b/docs/developer/core-concepts/orders.mdx
@@ -75,7 +75,14 @@ An order tracks payment and delivery separately, because they genuinely move at
| `delivered` | The customer has all of it |
| `canceled` | Nothing will be sent |
-A canceled parcel is ignored while others are still live, so an order whose second parcel was recalled is described by the first.
+A canceled parcel is ignored while others are still live, so an order whose
+second parcel was recalled is described by the first.
+
+`delivered` means every parcel arrived. A fulfillment that travels as several
+consignments — a machine in three boxes, a pallet under one freight number —
+is only delivered when the last of them lands, and the order follows from
+there. See [where the parcel actually
+is](/developer/core-concepts/fulfillments#where-the-parcel-actually-is).
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.
diff --git a/docs/developer/core-concepts/returns-exchanges-claims.mdx b/docs/developer/core-concepts/returns-exchanges-claims.mdx
index 60f89c2f6f..3139b5da01 100644
--- a/docs/developer/core-concepts/returns-exchanges-claims.mdx
+++ b/docs/developer/core-concepts/returns-exchanges-claims.mdx
@@ -21,6 +21,8 @@ erDiagram
Order ||--o{ Exchange : "has many"
Order ||--o{ Claim : "has many"
Return ||--o{ ReturnLineItem : "has many"
+ Return ||--o{ ShippingLabel : "prepays"
+ Return ||--o{ Delivery : "comes back as"
Return }o--|| StockLocation : "received at"
Return {
@@ -118,6 +120,51 @@ Receiving takes the quantities the warehouse actually counted, because partial a
Leave `items` out to receive everything as requested. Refunds default to whatever the return is still owed, and can go back to the original payment method or to store credit.
+### Where the goods come back to
+
+A return is received at a stock location. By default that is wherever the goods
+shipped from, which is right until a merchant inspects and restocks returns at
+one processing centre — so locations carry a `returns_enabled` flag, and a
+return routes to one that accepts them: the seller's for a seller's goods, the
+operator's own otherwise. Pass `stock_location_id` when opening the return to
+choose explicitly.
+
+### Prepaid return labels
+
+A return can carry its own postage. The label is bought against the same
+carrier account the outbound parcel shipped on, and the shipment is booked in
+reverse — from the customer's address back to the return's stock location.
+
+Buying one mints a delivery on the return, so the inbound parcel is tracked the
+same way an outbound one is. A delivery reporting arrival never receives the
+return: arrival is not inspection, and what actually turned up is still counted
+by hand.
+
+<CodeGroup>
+
+```typescript Admin SDK
+// Buy prepaid postage for the parcel coming back
+const label = await adminClient.orders.returns.labels.create('or_xxx', 'ret_xxx')
+
+// Or record one bought elsewhere
+await adminClient.orders.returns.labels.create('or_xxx', 'ret_xxx', {
+ file: signedBlobId,
+ tracking_number: '1Z999AA10123456784',
+})
+```
+
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/admin/orders/or_xxx/returns/ret_xxx/labels' \
+ -H 'X-Spree-API-Key: sk_xxx'
+```
+
+</CodeGroup>
+
+Customers download the label from the storefront, so a return request can end
+with "print this and drop it off" rather than an email exchange. See
+[shipping labels](/developer/core-concepts/fulfillments#shipping-labels) for
+how postage records work in general.
+
## Resolving a claim
What to do about a claim is decided when you resolve it, not when the customer opens it — merchants usually decide once they've seen the photos.