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.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Document consignments, shipping labels and return labels
Damian Legawiec9cd2d2b3d23e
diff --git a/docs/developer/core-concepts/fulfillments.mdx b/docs/developer/core-concepts/fulfillments.mdxindex 86b5e3b308..896538b26c 100644--- a/docs/developer/core-concepts/fulfillments.mdx+++ b/docs/developer/core-concepts/fulfillments.mdx@@ -14,6 +14,9 @@ erDiagramOrder ||--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 @@ erDiagramstring trackingstring costdatetime 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 youconst 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.mdxindex 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.mdxindex 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 @@ erDiagramOrder ||--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 aLeave `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 claimWhat 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.