@spree/docs 0.1.176 → 0.1.178

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

@@ -0,0 +1,278 @@
+---
+title: Fulfillments
+description: How Spree models getting items to the customer — fulfillments, delivery methods and zones, and delivery types covering shipping, digital and pickup.
+---
+
+## Overview
+
+A fulfillment is one batch of items going to the customer by one method — a parcel from a warehouse, a digital download, or an order waiting at a pickup counter. An order gets one fulfillment per combination of stock location and delivery method, so an order sourced from two warehouses has two.
+
+The word is deliberately broader than "shipment". A digital download has no carrier, no address and no package, and click-and-collect ships nowhere at all — a fulfillment covers all of them without dragging along fields that make no sense for most.
+
+```mermaid
+erDiagram
+    Order ||--o{ Fulfillment : "has many"
+    Fulfillment ||--o{ FulfillmentItem : "has many"
+    Fulfillment ||--o{ DeliveryRate : "offers"
+    Fulfillment }o--|| StockLocation : "sourced from"
+    DeliveryRate }o--|| DeliveryMethod : "priced by"
+    DeliveryMethod }o--o{ DeliveryZone : "serves"
+
+    Fulfillment {
+        string number
+        string status
+        string tracking
+        string cost
+        datetime fulfilled_at
+    }
+```
+
+## Fulfillment attributes
+
+| Attribute | Description |
+|---|---|
+| `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 |
+| `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 |
+
+## Statuses
+
+A fulfillment's status says what **you** did with the parcel — nothing else.
+
+| Value | Meaning |
+|---|---|
+| `unfulfilled` | Still with you. Nothing has left |
+| `fulfilled` | It went out — handed to the carrier, or waiting at the counter for a pickup order |
+| `delivered` | The customer has it |
+| `canceled` | It won't be sent |
+
+Statuses only move forward: once something has gone out it stays gone out, and a later payment problem changes the order's [payment status](orders.md#statuses) rather than the fulfillment.
+
+Whether a fulfillment *can* go out — the order is paid, nothing is on backorder — is checked when you fulfill it, and the answer comes back with a reason. It is not baked into the status, so a refund never moves a parcel backwards. Staff who need to ship against an invoice can pass `force`.
+
+### Where the parcel actually is
+
+Carrier reports live on a second field, `tracking_status`, and never change `status`:
+
+| Value | Meaning |
+|---|---|
+| `pre_transit` | Label made, carrier hasn't got it yet |
+| `in_transit` | On its way |
+| `out_for_delivery` | On the van |
+| `available_for_pickup` | Waiting at a carrier location |
+| `delivered` | Carrier says it arrived |
+| `return_to_sender` | Coming back to you |
+| `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`.
+
+`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 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.
+
+## Delivery types
+
+Every delivery method has a type that decides how it behaves:
+
+| Type | Behaviour |
+|---|---|
+| `shipping` | Physical delivery to an address. Someone marks it sent. |
+| `digital` | Available the moment the order is placed. No address needed. |
+| `pickup` | Collection from one of your own stock locations. |
+| `pickup_point` | Collection from a third-party point — a locker or partner shop. |
+
+This is what lets a store sell a downloadable album and a vinyl record in the same order without any special handling in your storefront: the download is ready immediately, the record gets a tracking number.
+
+## Choosing delivery at checkout
+
+Each fulfillment on a cart offers delivery rates. The customer picks one per fulfillment.
+
+
+```typescript Store SDK
+const cart = await client.carts.get(cartId)
+
+cart.fulfillments[0].delivery_rates
+// => [{ id: 'rate_xxx', name: 'DHL Express', display_cost: '$12.00',
+//       estimated_delivery_date: '2026-08-07' }, ...]
+
+await client.carts.fulfillments.update(cartId, cart.fulfillments[0].id, {
+  selected_delivery_rate_id: 'rate_xxx',
+})
+```
+
+```bash cURL
+curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx/fulfillments/ful_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" }'
+```
+
+
+Rates carry more than a price — carrier, service level and estimated delivery date — so you can show "DHL Express, arrives Tuesday" instead of just a number.
+
+## Pickup
+
+For pickup methods, ask the API where the customer can collect:
+
+
+```typescript Store SDK
+// Your own pickup-enabled locations
+const locations = await client.deliveryMethods.pickupLocations('dm_xxx')
+
+// Third-party pickup points near the customer
+const points = await client.deliveryMethods.pickupPoints('dm_xxx', {
+  latitude: 34.0522,
+  longitude: -118.2437,
+})
+```
+
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/delivery_methods/dm_xxx/pickup_locations' \
+  -H 'X-Spree-API-Key: pk_xxx'
+```
+
+
+## Managing fulfillments
+
+
+```typescript Admin SDK
+// What's still with you
+const fulfillments = await adminClient.orders.fulfillments.list('or_xxx')
+
+// Add tracking, then mark it sent
+await adminClient.orders.fulfillments.update('or_xxx', 'ful_xxx', {
+  tracking: '1Z999AA10123456784',
+})
+await adminClient.orders.fulfillments.fulfill('or_xxx', 'ful_xxx')
+
+// Ship only some of it — the chosen units split off and ship,
+// the rest stays open
+await adminClient.orders.fulfillments.fulfill('or_xxx', 'ful_xxx', {
+  items: [{ item_id: 'li_xxx', quantity: 1 }],
+})
+
+// Ship against an unpaid invoice — your call, not the API's
+await adminClient.orders.fulfillments.fulfill('or_xxx', 'ful_xxx', { force: true })
+
+// Record receipt yourself when no carrier reports it for you
+await adminClient.orders.fulfillments.markDelivered('or_xxx', 'ful_xxx')
+
+// Split it when only part can go now
+await adminClient.orders.fulfillments.split('or_xxx', 'ful_xxx', {
+  items: [{ fulfillment_item_id: 'fi_xxx', quantity: 1 }],
+})
+
+// Cancel
+await adminClient.orders.fulfillments.cancel('or_xxx', 'ful_xxx')
+```
+
+```bash cURL
+curl -X PATCH 'https://api.mystore.com/api/v3/admin/orders/or_xxx/fulfillments/ful_xxx' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{ "tracking": "1Z999AA10123456784" }'
+
+curl -X PATCH 'https://api.mystore.com/api/v3/admin/orders/or_xxx/fulfillments/ful_xxx/fulfill' \
+  -H 'X-Spree-API-Key: sk_xxx'
+```
+
+
+## Delivery methods and zones
+
+A **delivery method** is what the customer picks — "Standard", "Express", "Collect in store". A **delivery zone** decides where it's available.
+
+Zones match on country and state, and also on postal code prefixes and ranges, so you can offer same-day delivery to a handful of city postcodes without listing every one:
+
+```typescript Admin SDK
+await adminClient.deliveryZones.create({
+  name: 'London same-day',
+  members: [
+    { member_type: 'postal_code', country_code: 'GB', postal_code_prefix: 'SW1' },
+    { member_type: 'postal_code', country_code: 'GB', postal_code_from: 'EC1A', postal_code_to: 'EC1V' },
+  ],
+})
+```
+
+A zone member is either a whole country, a state, or a postal code prefix or range.
+
+> **NOTE:** Delivery zones cover delivery only. Tax is handled separately — see [Taxes](taxes.md).
+
+### Pricing and rules
+
+Delivery is priced either by a rule you configure in the dashboard — flat rate, per item, price bands — or by asking a carrier for live rates.
+
+Methods can also carry conditions that decide when they're offered at all: free shipping over a certain order value, or heavy items excluded from letter post. These are applied in one place, so both kinds of pricing respect them.
+
+## Adding your own statuses
+
+A made-to-order business — print on demand, furniture built after purchase —
+has a stage between "order placed" and "handed to the carrier". There are two
+ways to model it, and the lighter one is usually right.
+
+**Track production in your own model, gate handover with a hook.** A production
+pipeline usually has more resolution than one word — queued, printing, quality
+check, packed — and that detail belongs in your own tables or your
+integration's metadata, not in the parcel's lifecycle vocabulary. What core
+needs to know is only *whether the parcel may go out yet*, and that is exactly
+what the fulfill workflow's validate hook expresses:
+
+```ruby
+Spree.hooks.register('fulfillments.fulfill.validate') do |flow|
+  work_order = MyApp::WorkOrder.find_by(fulfillment: flow.fulfillment)
+  flow.reject!('still in production') unless work_order&.completed?
+end
+```
+
+The fulfillment stays `unfulfilled` while you build the thing; your storefront
+renders "we're making your furniture" as presentation, the same way pickup
+orders render `fulfilled` as "ready for pickup".
+
+**Add a real status when merchants need to act on the stage.** If staff filter
+by it, reports group by it, or webhooks fire on entering it, make it a
+first-class status:
+
+```ruby
+# an initializer
+Spree::Fulfillment.add_status('in_production', after: 'unfulfilled')
+```
+
+That gives you the `in_production?` predicate, the `.in_production` scope and
+a valid value. Moving into it is deliberately not declarative — write a small
+workflow, which is also where the printer submission or the workshop handoff
+belongs:
+
+```ruby
+class MyApp::Fulfillments::StartProduction < Spree::Workflow
+  def perform(fulfillment:)
+    super
+    step :ensure_startable      # refuse unless fulfillment.unfulfilled?
+    step :mark_in_production    # update!(status: 'in_production') + publish an event
+    external_step :submit_to_printer
+    success(fulfillment.reload)
+  end
+end
+```
+
+Core's own actions keep working on your status without overrides: the guards
+ask whether the parcel has *already gone out*, not whether it holds one of the
+built-in values, so an `in_production` fulfillment can still be fulfilled or
+canceled. Statuses are additive only — core workflows guard on core statuses,
+so removing one would silently break them — and confirmed receipt still only
+follows handover.
+
+## Events
+
+Fulfillments publish [events](events.md) — `fulfillment.created`, `fulfillment.fulfilled`, `fulfillment.delivered`, `fulfillment.canceled` — which also reach [webhooks](webhooks.md). Use them to notify a customer, push to a warehouse system, or send tracking emails.
+
+## Related
+
+- [Orders](orders.md) — how delivery status rolls up
+- [Inventory](inventory.md) — stock locations and availability
+- [Returns, Exchanges & Claims](returns-exchanges-claims.md) — items coming back

package/dist/developer/core-concepts/imports-exports.md

@@ -270,24 +270,12 @@ module Spree
     has_many :mappings    # Field mappings
     has_many :rows        # CSV rows to process
 
-    # State machine
-    state_machine initial: :pending do
-      event :start_mapping do
-        transition to: :mapping
-      end
-      event :complete_mapping do
-        transition from: :mapping, to: :completed_mapping
-      end
-      event :start_processing do
-        transition from: :completed_mapping, to: :processing
-      end
-      event :complete do
-        transition from: :processing, to: :completed
-      end
-      event :fail do
-        transition to: :failed
-      end
-    end
+    # Statuses. Each move between them is a workflow — Spree::Imports::
+    # StartMapping, CompleteMapping, StartProcessing, Complete and
+    # RetryFailedRows — so every step of the pipeline can be hooked.
+    include Spree::HasStatus
+    has_status :pending, :mapping, :completed_mapping, :processing, :completed, :failed,
+               default: :pending
 
     # Key methods
     def import_schema        # Returns schema class instance

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

@@ -82,7 +82,7 @@ erDiagram
 - **Stock Item** → Tracks quantity (`count_on_hand`) for a specific Variant at a specific Stock Location
 - **Stock Movement** → Records changes to Stock Item quantities (purchases, returns, transfers)
 - **Stock Transfer** → Moves inventory between Stock Locations, creating Stock Movements at source and destination
-- **Inventory Unit** → Represents individual units in [Orders](orders.md) and [Shipments](shipments.md)
+- **Inventory Unit** → Represents individual units in [Orders](orders.md) and [Shipments](fulfillments.md)
 - **Stock Reservation** → Time-limited soft hold on a Stock Item during checkout, scoped to a specific Order and Line Item
 
 ## Inventory Management
@@ -276,7 +276,7 @@ When a cart change in checkout would push the order beyond available stock, the
 
 ### Background expiry
 
-Abandoned checkouts leave behind expired reservation rows. Spree provides a job to clean them up but does **not** auto-schedule it — your application's job runner needs to invoke it periodically (every minute is typical). See the [5.4 to 5.5 upgrade guide](../upgrades/5.4-to-5.5.md#schedule-the-stock-reservations-expiry-job) for sidekiq-cron, solid_queue, and good_job snippets.
+Abandoned checkouts leave behind expired reservation rows. Spree provides a job to clean them up but does **not** auto-schedule it — your application's job runner needs to invoke it periodically (every minute is typical). See the [5.4 to 5.5 upgrade guide](/v5/developer/upgrades/5.4-to-5.5#schedule-the-stock-reservations-expiry-job) for sidekiq-cron, solid_queue, and good_job snippets.
 
 ### Backorderable items
 
@@ -319,7 +319,7 @@ If you don't need to track inventory, you can disable it:
 ## Related Documentation
 
 - [Products](products.md) - Product and variant management
-- [Shipments](shipments.md) - How inventory relates to shipments
+- [Shipments](fulfillments.md) - How inventory relates to shipments
 - [Orders](orders.md) - How inventory is allocated to orders
 - [Admin SDK resources](../sdk/admin/resources.md) - `stockLocations`, `stockItems`, and `stockTransfers` methods used in the examples above
 - [Admin API authentication](../../api-reference/admin-api/authentication.md) - How to obtain and scope the secret key (`sk_xxx`) used by these calls

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

@@ -104,7 +104,7 @@ Variants belonging to a different product are silently dropped — the API rejec
 
 The Store API's `media` field on a product returns its gallery — product-level media when present, falling back to legacy variant-pinned images during the transition. On a variant, `media` returns the assets linked to that variant via `variant_ids`, falling back to direct variant uploads.
 
-This dual rendering means existing storefronts keep working during the upgrade; new uploads attach to the product, and you opt into a [one-shot migration](../upgrades/5.4-to-5.5.md) to re-home legacy variant-pinned data when convenient.
+This dual rendering means existing storefronts keep working during the upgrade; new uploads attach to the product, and you opt into a [one-shot migration](/v5/developer/upgrades/5.4-to-5.5) to re-home legacy variant-pinned data when convenient.
 
 ### Video 
 

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

@@ -280,7 +280,7 @@ Spree has two permanent, complementary systems for custom data — **metadata fo
 
 **Use [Metadata](../customization/metadata.md)** for external system IDs, tracking attribution, syncing with integrations, or simple write-and-forget data that only backend systems need to read.
 
-> **WARNING:** Product Properties are deprecated and will be removed in Spree 6.0. For new projects, always use Metafields. For existing projects, plan to migrate using the [migration guide](../upgrades/5.1-to-5.2.md#migrate-to-metafields-or-keep-using-product-properties).
+> **WARNING:** Product Properties are deprecated and will be removed in Spree 6.0. For new projects, always use Metafields. For existing projects, plan to migrate using the [migration guide](/v5/developer/upgrades/5.1-to-5.2#migrate-to-metafields-or-keep-using-product-properties).
 
 ## Related Documentation