@spree/docs 0.1.240 → 0.1.242

package/dist/api-reference/store-api/metadata.md

@@ -6,7 +6,7 @@ description: "How to store and retrieve custom metadata on carts, orders, and li
 
 The Store API supports storing arbitrary key-value **metadata** on carts (orders) and line items. Metadata is useful for tracking custom information like gift messages, attribution data, or integration-specific fields.
 
-> **NOTE:** Metadata is different from [metafields](../../developer/core-concepts/metafields.md). Metadata is simple JSON storage (untyped, no schema), while metafields are structured, typed, and schema-defined. Use metadata for integration data and internal tracking. Use metafields for customer-facing custom attributes.
+> **NOTE:** Metadata is different from [custom fields](../../developer/core-concepts/metafields.md). Metadata is simple JSON storage (untyped, no schema), while custom fields are structured, typed, and schema-defined. Use metadata for integration data and internal tracking. Use custom fields for customer-facing custom attributes.
 
 ## Cart Metadata
 
@@ -146,18 +146,18 @@ Metadata is stored as a flat JSON object. You can use any keys and values:
 }
 ```
 
-## Metadata vs Metafields
+## Metadata vs Custom Fields
 
-Spree has two permanent, complementary systems for custom data — **metadata for machines, metafields for humans**.
+Spree has two permanent, complementary systems for custom data — **metadata for machines, custom fields for humans**.
 
-| | Metadata | Metafields |
+| | Metadata | Custom Fields |
 |-|----------|------------|
 | **Purpose** | Developer escape hatch — integration IDs, sync state | Merchant-defined structured attributes |
-| **Schema** | Schemaless JSON — no definition required | Defined via MetafieldDefinitions (typed, validated) |
+| **Schema** | Schemaless JSON — no definition required | Defined via CustomFieldDefinitions (typed, validated) |
 | **Validation** | None | Type-specific validation |
 | **Visibility** | Write-only in Store API, readable in Admin API | Configurable (admin-only or public) |
 | **Admin UI** | JSON preview | Dedicated form fields |
 | **Best for** | Integration data, tracking, attribution, write-and-forget | Product specs, custom attributes, customer-facing data |
 | **API access** | Write via Store API, read via Admin API | Read/write via both APIs |
 
-Both systems are here to stay. For more details on metafields, see the [Metafields guide](../../developer/core-concepts/metafields.md).
+Both systems are here to stay. For more details on custom fields, see the [Custom Fields guide](../../developer/core-concepts/metafields.md).

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

@@ -5,9 +5,10 @@ description: How Spree fits together — the catalog, the cart, the order, and f
 
 ## Overview
 
-Spree is a commerce engine you drive through a REST API. It holds the catalog, works out what a customer owes, takes the money, and tracks what was sent. You build the storefront, the mobile app, or the internal tool on top of it.
+Spree is a commerce engine you drive through a REST API. It holds the catalog, works out what a customer owes, takes the money, and tracks what was delivered. You build the storefront, the mobile app, Point of Sale or an internal tool on top of it.
 
-There is no built-in storefront you have to accept. Everything a customer-facing app needs is on the Store API, and everything a back office needs is on the Admin API. Both ship as typed TypeScript clients.
+There is no built-in storefront you have to accept, however we do provide a [reference one built in Next.js](../storefront/nextjs/quickstart.md). 
+Everything a customer-facing app needs is on the Store API, and everything a back office needs is on the Admin API. Both ship as fully typed TypeScript clients.
 
 ## The shape of a purchase
 
@@ -72,7 +73,7 @@ Three things in that diagram are worth calling out, because they're where Spree
 
 **Delivery is described by a profile, not a category.** A [delivery profile](fulfillments.md) says how a product travels — physically shipped, or digital — and which locations and methods serve it.
 
-**Stock lives per location.** A variant has a stock level at each [stock location](inventory.md), so availability is a real question about real warehouses rather than a single number.
+**Stock lives per location.** A variant can have a stock level at each [stock location](inventory.md), so availability is a real question about real warehouses rather than a single number.
 
 ## The two APIs
 
@@ -103,6 +104,7 @@ Spree assumes you'll extend it, and gives you three ways in that survive an upgr
 
 | Approach | Use it for | Guide |
 |---|---|---|
+| **Events** | Reacting inside your own app when something happens — indexing a record, calling an API with your credentials | [Events](events.md) |
 | **Webhooks** | Telling another system something happened — an ERP, a warehouse, an email tool | [Webhooks](webhooks.md) |
 | **Custom fields** | Storing your own data on a product, order or customer without changing the schema | [Custom Fields](metafields.md) |
 | **Providers** | Plugging in a real service for tax, delivery rates, payments or search | [Providers](../providers/overview.md) |
@@ -116,32 +118,26 @@ One Spree installation can run more than one business:
 - **[Stores](stores.md)** are separate businesses — their own catalog, orders, customers and settings. Data does not cross between them.
 - **[Channels](channels.md)** are the ways one store sells: a website, a mobile app, a retail till.
 - **[Markets](markets.md)** are the regions a store sells into, each with its currency, locale and tax treatment.
-- **[Sellers](products.md#seller-submissions)** let one store list goods from many vendors, for a marketplace.
+- **[Sellers](sellers.md)** let one store list goods from many vendors, for a marketplace.
 
 ## What you install
 
-| Package | What it is |
-|---|---|
-| `spree` | The engine — catalog, checkout, payments, both APIs |
-| `spree_emails` | Transactional email, if you don't send your own |
-| `spree_dashboard` | The back-office dashboard |
-
-Providers for search, delivery rates, tax and payments install separately, so you only carry what you use.
-
-**TypeScript:**
-
 | Package | What it is |
 |---|---|
 | [`@spree/sdk`](../sdk/quickstart.md) | Store API client — for your storefront |
 | [`@spree/admin-sdk`](../sdk/admin/quickstart.md) | Admin API client — for back-office and integrations |
 | [`@spree/cli`](../cli/quickstart.md) | Command line for local setup and calling the Admin API |
+| [`@spree/dashboard`](../dashboard/overview.md) | The admin interface, a React app you own and extend |
 
-> **INFO:** Spree runs on PostgreSQL, MySQL or SQLite. PostgreSQL is recommended for production — [database configuration](../deployment/database.md).
+> **INFO:** Spree runs on PostgreSQL, MySQL or SQLite. Check [database configuration](../deployment/database.md) for more details.
 
 ## Where to go next
 
+Two ways in, depending on how you prefer to learn.
+
+
+  - [Build something](../tutorial/introduction.md) — Add one feature end to end — a model with its own API, a screen in the dashboard, a page on the storefront, and the tests around it. Start here if you learn by doing.
+  - [Read the reference](products.md) — Every part of the platform, one page each: products and pricing, carts and orders, payments, fulfillment, promotions. Start here if you already know what you need.
+
 
-  - [Quickstart](../getting-started/quickstart.md) — Get an installation running.
-  - [Store SDK](../sdk/quickstart.md) — Build a storefront against the Store API.
-  - [Products](products.md) — How the catalog is modelled.
-  - [Carts](carts.md) — Cart, checkout, and what completion guarantees.
+Building a storefront rather than extending the backend? Go straight to the [Spree Next.js Storefront](../storefront/nextjs/quickstart.md).

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

@@ -131,10 +131,80 @@ A cart tells you what it still needs before it can be completed:
 }
 ```
 
-An empty `requirements` array means the cart is ready.
+Every entry has the same four fields. Branch on `code` — `message` is translated prose
+meant for a person, and `step` is only a grouping hint.
 
 This is what lets you design your own checkout. Spree tells you what's missing; you decide how and when to ask for it — one long page, a few steps, or whatever suits your storefront.
 
+Seven checks run on every cart read:
+
+| `code` | `step` | Raised when |
+|---|---|---|
+| `line_items_required` | `cart` | The cart is empty |
+| `email_required` | `address` | No email address |
+| `ship_address_required` | `address` | Something needs shipping and there is no address |
+| `delivery_method_required` | `delivery` | A delivery method hasn't been chosen |
+| `payment_required` | `payment` | The total isn't covered by payments |
+| `po_number_required` | `address` | A company requires a purchase-order number |
+| `order_minimum_not_met` | `cart` | Below the order minimum, with the shortfall in the message |
+
+> **WARNING:** **An empty `requirements` array does not guarantee completion will succeed.** What a
+>   cart reports is the *advisory* set. Completing one additionally checks stock
+>   (`out_of_stock`, `discontinued`), negotiated quantity rules
+>   (`quantity_rule_violated`) and the guest-checkout policy
+>   (`guest_checkout_not_allowed`) — each of which has to load line items, so they are
+>   held back to keep reading a cart cheap. Treat a failed completion as a normal path,
+>   not an exception.
+
+### Checkout steps
+
+A cart also reports a step list, so you can render a progress indicator:
+
+
+```typescript Store SDK
+const cart = await client.carts.get(cartId)
+
+cart.current_step     // "delivery"
+cart.completed_steps  // ["address"]
+```
+
+```json Response
+{
+  "current_step": "delivery",
+  "completed_steps": ["address"]
+}
+```
+
+
+Spree has no checkout state machine. The list is computed from the cart's own data,
+and nothing on the server refuses a write because of where the customer appears to be
+— you can set an address, choose delivery and attach a payment in any order.
+`current_step` is simply the step of the first unmet requirement.
+
+Five steps are built in, and three only appear when they apply:
+
+| Step | Present when |
+|---|---|
+| `address` | Always |
+| `delivery` | The cart has items and isn't entirely digital |
+| `payment` | The total is above zero |
+| `confirm` | A payment method asks for one, or the store always wants one |
+| `complete` | Always |
+
+So a free digital order reports `address` then `complete`. A storefront that hardcodes
+five steps will show two that never apply.
+
+> **NOTE:** Requirements use one grouping name that is not a step: **`cart`**. Missing line
+>   items, the order minimum and stock problems are filed under it, and there is no
+>   `cart` entry in the step list — `current_step` reports those as `address`. If you
+>   group requirements by `step` to place them on screens, give `cart` a home.
+
+Checkout introspection lives on the cart, not the order. An order has already been
+placed, so `current_step` and `requirements` do not appear on it.
+
+To add your own step or requirement, see
+[Customizing checkout](../customization/checkout.md).
+
 ## Checkout
 
 **Step 1: Add the customer's details**

package/dist/developer/core-concepts/delivery-setup.md

@@ -155,7 +155,8 @@ otherwise every parcel is quoted light.
 
 Package types are that vocabulary: the box parcels ship in, and for wholesale,
 the cartons products are packed into and the pallets or containers an order
-leaves on.
+leaves on. How those cartons and pallets roll up into a quote is
+[freight](freight.md).
 
 
 ```typescript Admin SDK
@@ -248,6 +249,7 @@ box of their own with all three dimensions and a weight recorded. See
 
 ## Related
 
+- [Freight](freight.md) — cartons, pallets and wholesale shipping
 - [Fulfillments](fulfillments.md) — what happens to the parcel afterwards
 - [Calculators](calculators.md) — how a price is worked out
 - [EasyPost](../../integrations/shipping/easypost.md) — live carrier rates and labels

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

@@ -0,0 +1,279 @@
+---
+title: Freight
+description: How wholesale orders ship — the carton and pallet chain a product declares, the logistics rollup a forwarder quotes against, and rates that carry no price yet.
+---
+
+## Overview
+
+A wholesale order does not leave the warehouse as parcels. It leaves as
+cartons, a pallet, or a container, and for international freight the price is
+quoted by a forwarder after someone looks at the order — not by an API at
+checkout.
+
+Four pieces make that work, and none of them disturb retail shipping:
+
+| Piece | Question it answers |
+|---|---|
+| **Carton details** on a product | How do these units pack? |
+| **Freight summary** on a cart or order | How big is the whole load? |
+| **Volume and company rules** on a delivery method | Which shipment tier is this? |
+| **Unpriced rates** | What does a buyer see before a price exists? |
+
+One catalog serves both audiences. The same product ships parcel to a shopper
+and carton to a trade buyer, because freight methods sit on the ordinary
+shipping profile and are gated by who is buying rather than by what is bought.
+See [delivery setup](delivery-setup.md) for profiles,
+zones and methods, and [package types](delivery-setup.md#packaging)
+for the packaging vocabulary this builds on.
+
+## How products pack
+
+Freight numbers are not derivable from retail shipping data. A case of 48
+bottles is one carton, not 48 parcels — so a product says how its units pack,
+and the rest follows the chain **unit → carton → pallet → cubic meters and
+weight**.
+
+The geometry lives on a shared carton, because merchants reuse a handful of
+standard sizes across hundreds of products and one edit should fix all of
+them. What varies per product stays on the product:
+
+| Field | What it says |
+|---|---|
+| `carton_package_type_id` | Which carton this is packed into. Must be a package type of kind `carton` |
+| `units_per_carton` | How many units one carton holds |
+| `carton_weight` | What a packed carton weighs, gross. Optional |
+| `cartons_per_pallet` | How those cartons stack |
+| `purchase_unit` | `unit` or `carton` — what a buyer is quoted in |
+
+
+```typescript Admin SDK
+// The carton, once, shared by every product packed in it.
+const carton = await adminClient.packageTypes.create({
+  name: 'Master carton',
+  kind: 'carton',
+  length: 40, width: 30, height: 25, dimensions_unit: 'cm',
+  weight: 0.4, max_weight: 20, weight_unit: 'kg',
+})
+
+// How this product fills it.
+await adminClient.products.variants.update('prod_xxx', 'variant_xxx', {
+  carton_package_type_id: carton.id,
+  units_per_carton: 48,
+  carton_weight: 19.2,
+  cartons_per_pallet: 40,
+  purchase_unit: 'carton',
+})
+```
+
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/admin/package_types' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "name": "Master carton", "kind": "carton",
+    "length": 40, "width": 30, "height": 25, "dimensions_unit": "cm",
+    "weight": 0.4, "max_weight": 20, "weight_unit": "kg"
+  }'
+
+curl -X PATCH 'https://api.mystore.com/api/v3/admin/products/prod_xxx/variants/variant_xxx' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "carton_package_type_id": "pkgtype_xxx",
+    "units_per_carton": 48,
+    "carton_weight": 19.2,
+    "cartons_per_pallet": 40,
+    "purchase_unit": "carton"
+  }'
+```
+
+
+Stored quantities are always units, at every level. `purchase_unit` only
+changes the vocabulary a storefront presents — a buyer shown "2 cartons" is
+buying 96 units.
+
+Two data errors are refused while the merchant is still editing rather than
+discovered through a customer complaint: an `order_multiple` that straddles
+carton boundaries can never ship whole, and quoting in cartons without saying
+how many units one holds leaves a storefront no way to render the offer.
+
+Reading a product back adds `units_per_pallet`, derived from the two divisors
+so a merchant sees the far end of the chain without doing the arithmetic. It
+is null unless both halves are recorded.
+
+> **NOTE:** A product may only be packed into a package type of kind `carton`, and a
+> carton with products packed into it cannot later become a pallet. Repack the
+> products first.
+
+## The freight summary
+
+The **freight summary** is the load as a forwarder reads it: how many units,
+the cartons they fill, the pallets those stack onto, the cubic meters they
+occupy and what the whole thing weighs.
+
+```json
+{
+  "total_units": 480,
+  "total_cartons": 10,
+  "total_pallets": 1,
+  "total_volume": "0.3",
+  "total_weight": "192.0",
+  "complete": true
+}
+```
+
+`total_volume` is cubic meters and `total_weight` is kilograms, both as
+decimal strings. `total_pallets` is null unless every carton-bearing line says
+how it stacks — one silent product would understate the load, so no figure is
+better than a wrong one.
+
+**`complete` is the field to read before quoting from any of it.** False means
+part of the catalog carries no carton data, so those products were measured
+loose from their unit dimensions instead. The numbers are still the best
+available and real enough to quote against, but they are a floor rather than a
+total, and a surface using them should say so.
+
+A cart of unmeasured goods has no freight summary at all rather than one full
+of zeros, which would read as a shipment that takes up no space.
+
+### Where it appears
+
+| Response | Shape |
+|---|---|
+| Store cart | Totals only |
+| Store delivery rate | Totals only, on freight rates |
+| Admin cart and order | Totals plus a `lines` breakdown |
+| Admin delivery rate | Totals plus `lines` |
+
+The per-product breakdown is back-office only. A buyer is told what their
+shipment costs and how big it is; which SKU accounts for which part of it is
+the warehouse's business. Each admin line carries `variant_id`, `sku`, `name`,
+`units`, `cartons`, `pallets`, `units_per_carton`, `cartons_per_pallet`,
+`weight_per_carton`, `volume`, `weight` and its own `complete` flag.
+
+
+```typescript SDK
+const cart = await client.carts.get('cart_xxx')
+
+if (cart.freight_summary) {
+  const { total_cartons, total_pallets, total_volume, complete } = cart.freight_summary
+  // `complete: false` — show these as a minimum, not a total.
+}
+```
+
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/carts/cart_xxx' \
+  -H 'X-Spree-API-Key: pk_xxx' \
+  -H 'X-Spree-Token: guest_token'
+```
+
+
+> **NOTE:** A placed order's summary is never re-derived from the live catalog. The freight
+> provider freezes a copy onto the rate it quoted, and the order reads that — so
+> a carton size corrected next month does not rewrite what this container held.
+> Two freight consignments on one order are merged into the one load the
+> forwarder sees, and a canceled one is left out.
+
+## Freight rates
+
+A freight method is an ordinary [delivery method](delivery-setup.md#delivery-methods-and-zones)
+priced by the **Freight** rate provider. That provider quotes nothing and says
+so: it returns a rate with no price, carrying the freight summary the merchant
+will send to the forwarder in place of an amount.
+
+Such a rate comes back with `unpriced: true`, and every money field on it reads
+**"Quoted after review"** rather than a figure. That matters: a zero cost
+rendering as "Free" over a container of goods is a promise the merchant cannot
+keep. Unpriced rates are also sorted after every priced one and are never
+preselected, so a buyer with a real parcel option still sees it first.
+
+
+```typescript SDK
+const rates = fulfillment.delivery_rates
+
+rates.forEach((rate) => {
+  if (rate.unpriced) {
+    rate.display_total       // "Quoted after review"
+    rate.freight_summary     // what the forwarder will quote against
+  } else {
+    rate.display_total       // "$24.00"
+  }
+})
+```
+
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/carts/cart_xxx' \
+  -H 'X-Spree-API-Key: pk_xxx' \
+  -H 'X-Spree-Token: guest_token'
+```
+
+
+Checkout completes on an unpriced rate. The shipping price arrives afterwards,
+once the forwarder has quoted it.
+
+> **NOTE:** How a wholesale buyer **pays** — deposits, net terms, credit limits — is a
+> separate subject and is not part of freight in 6.0. Partial payments are
+> generally available and predate this work. See
+> [payments](payments.md).
+
+## Shipment tiers
+
+Which freight method a load qualifies for is configuration, not code. Each
+tier — "Cartons", "Pallet", "20ft container" — is an ordinary delivery method
+bounded by a rule.
+
+**Volume rule.** Bounds the method by packed volume in cubic meters: a pallet
+method takes 1–15 CBM, a 20ft container 15–33, and the estimator offers
+whichever one the order actually fills.
+
+Its minimum is deliberately forgiving. A partly measured catalog understates
+the load, so the figure is a floor rather than a measurement — it may raise a
+shipment into a tier but never exclude it from one. A maximum still applies,
+since passing one on too small a number errs toward offering the method.
+
+**Company rule.** Splits freight from parcel by who is buying. On, the method
+is offered only to orders placed for a [company](companies.md),
+so a carton tier disappears from retail carts. Off, only to orders that are
+not, which keeps parcel methods away from wholesale buyers. A method with no
+company rule is offered to both, so the rule is only ever added to state a
+split.
+
+
+```typescript Admin SDK
+await adminClient.deliveryMethods.create({
+  name: 'Pallet freight',
+  rate_provider: 'Spree::DeliveryRateProvider::Freight',
+  rules: [
+    { type: 'volume_rule', preferences: { minimum_volume: 1, maximum_volume: 15 } },
+    { type: 'company_rule', preferences: { company_orders_only: true } },
+  ],
+})
+```
+
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/admin/delivery_methods' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "name": "Pallet freight",
+    "rate_provider": "Spree::DeliveryRateProvider::Freight",
+    "rules": [
+      { "type": "volume_rule", "preferences": { "minimum_volume": 1, "maximum_volume": 15 } },
+      { "type": "company_rule", "preferences": { "company_orders_only": true } }
+    ]
+  }'
+```
+
+
+A freight method never consults a calculator — there is no price to work out —
+so admin surfaces hide its pricing form. `GET /api/v3/admin/delivery_methods/rate_providers`
+lists the providers installed on the store, which is what a picker should read
+rather than a hardcoded list.
+
+## Related
+
+- [Delivery setup](delivery-setup.md) — profiles, zones, methods and package types
+- [Fulfillments](fulfillments.md) — what happens to the consignment afterwards
+- [Companies](companies.md) — who a wholesale order is placed for
+- [Build a B2B store](../how-to/build-a-b2b-store.md) — the wholesale setup end to end
+- [Package types](/user/settings/package-types) — configuring packaging in the dashboard

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

@@ -9,8 +9,6 @@ Sooner or later you need to store something Spree doesn't have a field for. A fa
 
 Custom fields are how you do that without changing the database. You declare a field once — its name, its type, who can see it — and from then on it can be set on any record of that kind, edited in the dashboard, returned by the API, and searched or filtered like any built-in field.
 
-> **NOTE:** Custom fields are also known as **metafields** in the dashboard. The API and SDK call them custom fields throughout.
-
 ## Definitions and values
 
 There are two halves, and it helps to keep them straight: