@spree/docs 0.1.181 → 0.1.183

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

@@ -1,148 +1,125 @@
 ---
-title: Metafields
-description: Add custom structured data to products, orders, and other resources with type-safe metafields
+title: Custom Fields
+description: Add your own structured, typed data to products, orders and other records — searchable, filterable, and editable in the dashboard.
 ---
 
-import { Since } from '/snippets/since.mdx';
-
-
 ## Overview
 
-Metafields provide a flexible, type-safe system for adding custom structured attributes to Spree models. Unlike [metadata](../customization/metadata.md) which is simple JSON storage, metafields are schema-defined with strong typing, validation, and visibility controls.
+Sooner or later you need to store something Spree doesn't have a field for. A fabric composition. A care instruction. A gift message. An ID from the system you sync with.
+
+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.
 
-Use metafields for:
+> **NOTE:** Custom fields were called **metafields** before Spree 6.0. The API and SDK have always called them custom fields; now the rest of Spree does too.
 
-- Product specifications (manufacturer, material, dimensions)
-- Custom business logic fields
-- Integration data from external systems
-- Order-specific custom attributes
+## Definitions and values
 
-## Architecture
+There are two halves, and it helps to keep them straight:
 
 ```mermaid
 erDiagram
-    MetafieldDefinition ||--o{ Metafield : "defines schema for"
-    Product ||--o{ Metafield : "has many"
-    Variant ||--o{ Metafield : "has many"
-    Order ||--o{ Metafield : "has many"
+    CustomFieldDefinition ||--o{ CustomField : "gives shape to"
+    Product ||--o{ CustomField : "has values"
+    Order ||--o{ CustomField : "has values"
+    Customer ||--o{ CustomField : "has values"
 
-    MetafieldDefinition {
+    CustomFieldDefinition {
         string namespace
         string key
-        string name
-        string metafield_type
+        string label
+        string field_type
         string resource_type
-        string display_on
+        boolean storefront_visible
         boolean searchable
         boolean sortable
     }
 
-    Metafield {
-        string type
-        text value
-        string resource_type
+    CustomField {
+        string key
+        string label
+        string field_type
+        any value
     }
 ```
 
-```mermaid
-flowchart LR
-    subgraph Definition
-        A[MetafieldDefinition] --> B["namespace: properties"]
-        A --> C["key: manufacturer"]
-        A --> D["type: ShortText"]
-        A --> E["resource_type: Product"]
-        A --> F["display_on: both"]
-    end
-
-    subgraph Instance
-        G[Metafield] --> H["value: Wilson"]
-        G --> I["resource: Product #1"]
-    end
-
-    A -.->|"defines schema"| G
-```
-
-- **MetafieldDefinition** — the blueprint that defines the data type, target resource, and visibility
-- **Metafield** — stores the actual value for a specific resource instance
-
-## Data Types
+- A **definition** is the declaration: "products have a Material, it is short text, shoppers may see it." You create it once.
+- A **custom field** is one record's answer: this product's material is `100% Cotton`.
 
-| Type | Description | Example Values |
-|------|-------------|----------------|
-| Short Text | Brief text fields | SKU codes, brand names, tags |
-| Long Text | Longer text content | Care instructions, notes |
-| Rich Text | Formatted HTML content | Product descriptions with formatting |
-| Number | Numeric values | Weight, quantity, ratings |
-| Boolean | True/false flags | Is featured, requires signature |
-| JSON | Structured data | Configuration, complex objects |
+Because the definition carries the type and the label, the dashboard can build an editing form for it automatically, and your storefront gets a value it can trust the shape of.
 
-## Visibility Control
+## Field types
 
-Metafields support two visibility levels via the `display_on` attribute:
+| Type | For | Example |
+|---|---|---|
+| `short_text` | A word or a line | `Wilson`, `100% Cotton` |
+| `long_text` | A paragraph | Care instructions |
+| `rich_text` | Formatted HTML | A spec sheet with lists and bold |
+| `number` | A quantity or measure | `3.5`, `120` |
+| `boolean` | A yes or no | Requires a signature |
+| `json` | Structured data | A sizing chart |
 
-| Visibility | Store API | Admin API | Use Case |
-|------------|:---------:|:---------:|----------|
-| `both` | Yes | Yes | Public product specifications |
-| `back_end` | No | Yes | Internal notes, integration IDs |
+## Who can see it
 
-## Search, sort & filter
+`storefront_visible` decides whether a field ever leaves the back office:
 
-Product metafield definitions can opt into SearchProvider participation:
+| `storefront_visible` | Store API | Admin API | Use it for |
+|---|:---:|:---:|---|
+| `true` | Yes | Yes | Anything a shopper should see — materials, specs |
+| `false` | No | Yes | Internal notes, supplier codes, sync IDs |
 
-| Flag | Effect | Allowed field types |
-|------|--------|---------------------|
-| `searchable` | Values are included in product text search | `short_text`, `long_text`, `number` |
-| `sortable` | Listings can sort with `sort=cf_{namespace}_{key}` (prefix `-` for descending), e.g. `cf_custom_label` | `short_text`, `number` |
+> **WARNING:** `storefront_visible: false` genuinely withholds the field from the Store API — it is not hidden in the response, it is absent. Treat it as the boundary between what a customer may read and what only staff may.
 
-Both default to `false`. Set them on the definition (Admin UI, Admin API, or seeds). For an existing catalog with Meilisearch, run `rake spree:search:reindex` after toggling flags so index settings and product documents pick up new `cf_*` fields.
+## Declaring a field
 
-### Filtering
 
-Any definition with either flag set also becomes filterable on product listings, using its `cf_*` key as a Ransack predicate. The Store and Admin APIs accept the same keys and the same `sort` values:
-
-```
-GET /api/v3/store/products?q[cf_custom_material_i_cont]=wool
-GET /api/v3/admin/products?q[cf_custom_weight_gteq]=3.5
-GET /api/v3/store/products?sort=-cf_custom_weight
+```typescript Admin SDK
+const definition = await adminClient.customFieldDefinitions.create({
+  resource_type: 'Spree::Product',
+  namespace: 'properties',
+  key: 'material',
+  label: 'Material',
+  field_type: 'short_text',
+  storefront_visible: true,
+  searchable: true,
+})
 ```
 
-| Field type | Predicates |
-|------------|------------|
-| `short_text`, `long_text` | `i_cont`, `cont`, `eq`, `not_eq`, `start`, `end`, `present`, `blank` |
-| `number` | `eq`, `gt`, `gteq`, `lt`, `lteq`, `present`, `blank` |
-
-Use `i_cont` for case-insensitive matching — plain `cont` is case-sensitive on PostgreSQL.
-
-Predicates that don't match the definition's field type are ignored rather than rejected, as are keys matching no definition. Meilisearch supports the equality, range, and `present`/`blank` predicates; substring predicates (`i_cont`, `cont`, `start`, `end`) apply only to the database provider.
-
-CSV exports honor the same predicates, so exporting a filtered product list matches what the admin sees.
-
-In the admin dashboard, these fields appear in the products table's column selector, Sort dropdown, and filter panel — hidden by default, so admins opt in per column.
-
-## Supported Resources
+```bash CLI
+spree api post /custom_field_definitions -d '{
+  "resource_type": "Spree::Product",
+  "namespace": "properties",
+  "key": "material",
+  "label": "Material",
+  "field_type": "short_text",
+  "storefront_visible": true,
+  "searchable": true
+}'
+```
 
-Metafields can be attached to most Spree resources including Products, Variants, Orders, Line Items, Taxons, Payments, Shipments, Gift Cards, Store Credits, and more.
 
-> **INFO:** Custom resources can also support metafields. See the [Customization Quickstart](../customization/quickstart.md) for details.
+`namespace` keeps groups of fields apart, so an integration's `product_id` never collides with yours. Together they form the key you'll see in responses: `properties.material`. Both are normalized to snake_case.
 
-## Namespaces
+Definitions can also be managed in the dashboard under **Settings → Custom Fields**, which is where merchants usually add them.
 
-Namespaces organize metafields into logical groups and prevent key conflicts:
+## Setting and reading values
 
-| Namespace | Example Keys | Purpose |
-|-----------|-------------|---------|
-| `properties` | `manufacturer`, `material`, `fit` | Product specifications |
-| `shopify` | `product_id`, `variant_id` | Integration data |
-| `flags` | `featured`, `requires_approval` | Feature flags |
-| `custom` | `gift_message`, `delivery_notes` | Business-specific fields |
 
-> **INFO:** Namespace and key are automatically normalized to snake_case.
+```typescript Admin SDK
+// Set a value on a product
+await adminClient.products.customFields.create('prod_xxx', {
+  custom_field_definition_id: definition.id,
+  value: '100% Cotton',
+})
+```
 
-## Store API
+```bash CLI
+spree api post /products/prod_xxx/custom_fields -d '{
+  "custom_field_definition_id": "cfdef_xxx",
+  "value": "100% Cotton"
+}'
+```
 
-Metafields with `display_on` set to `both` are included in Store API responses when you [request the `custom_fields` expand](../../api-reference/store-api/relations.md):
 
-> **INFO:** Metafields in API are called Custom Fields as we plan to rename Metafields to Custom Fields completely in Spree 6.0.
+Reading them from a storefront is an expand on whatever you already fetch:
 
 
 ```typescript Store SDK
@@ -150,44 +127,29 @@ const product = await client.products.get('spree-tote', {
   expand: ['custom_fields'],
 })
 
-product.custom_fields?.forEach(field => {
-  console.log(field.key)   // "properties.manufacturer"
-  console.log(field.label) // "Manufacturer"
-  console.log(field.value)      // "Wilson"
-  console.log(field.field_type) // "short_text"
-})
-```
-
-```typescript Admin SDK
-const product = await adminClient.products.get('prod_86Rf07xd4z', {
-  expand: ['custom_fields'],
+product.custom_fields?.forEach((field) => {
+  field.key        // "properties.material"
+  field.label      // "Material"
+  field.value      // "100% Cotton"
+  field.field_type // "short_text"
 })
 ```
 
 ```bash cURL
 curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=custom_fields' \
-  -H 'X-Spree-Api-Key: pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 
-**Response:**
-
-```json
+```json Response
 {
   "id": "prod_86Rf07xd4z",
-  "name": "Spree T-Shirt",
+  "name": "Spree Tote",
   "custom_fields": [
     {
       "id": "cf_k5nR8xLq",
-      "label": "Manufacturer",
-      "key": "properties.manufacturer",
-      "field_type": "short_text",
-      "value": "Wilson"
-    },
-    {
-      "id": "cf_m3Rp9wXz",
-      "label": "Material",
       "key": "properties.material",
+      "label": "Material",
       "field_type": "short_text",
       "value": "100% Cotton"
     }
@@ -195,96 +157,57 @@ curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=custom_fie
 }
 ```
 
-> **NOTE:** The `display_on` attribute is intentionally excluded from Store API responses for security.
-
-## Admin Management
-
-### Managing Definitions
+Each value arrives with its own label and type, so you can render a spec table straight from the array without hardcoding which fields exist.
 
-Navigate to **Settings → Metafield Definitions** in the Admin Panel to create and manage metafield definitions. Select the resource type, enter namespace and key, choose the data type, and set visibility.
+## Searching, sorting and filtering
 
-Definitions are also [managed via the Admin API](../../api-reference/admin-api/endpoints.md). `storefront_visible: true` is equivalent to `display_on: both` — it exposes the field to the Store API:
+A custom field can take part in product listings — but only if you ask, because indexing everything by default would be wasteful.
 
+| Flag | What it enables | Works with |
+|---|---|---|
+| `searchable` | The value is matched by product text search | `short_text`, `long_text`, `number` |
+| `sortable` | Listings can be ordered by it | `short_text`, `number` |
 
-```typescript Admin SDK
-import { createAdminClient } from '@spree/admin-sdk'
-
-const client = createAdminClient({
-  baseUrl: 'https://store.example.com',
-  secretKey: 'sk_xxx',
-})
-
-const definition = await client.customFieldDefinitions.create({
-  resource_type: 'Spree::Product',
-  namespace: 'properties',
-  key: 'manufacturer',
-  label: 'Manufacturer',
-  field_type: 'short_text',
-  storefront_visible: true,
-})
+Setting either flag also makes the field **filterable**. Filter and sort with the field's `cf_` key, on both APIs:
 
-await client.customFieldDefinitions.update(definition.id, { storefront_visible: false })
-await client.customFieldDefinitions.delete(definition.id)
 ```
-
-```bash CLI
-spree api post /custom_field_definitions -d '{
-  "resource_type": "Spree::Product",
-  "namespace": "properties",
-  "key": "manufacturer",
-  "label": "Manufacturer",
-  "field_type": "short_text",
-  "storefront_visible": true
-}'
+GET /api/v3/store/products?q[cf_properties_material_i_cont]=wool
+GET /api/v3/store/products?sort=-cf_properties_weight
+GET /api/v3/admin/products?q[cf_properties_weight_gteq]=3.5
 ```
 
+| Field type | Comparisons available |
+|---|---|
+| `short_text`, `long_text` | `i_cont`, `cont`, `eq`, `not_eq`, `start`, `end`, `present`, `blank` |
+| `number` | `eq`, `gt`, `gteq`, `lt`, `lteq`, `present`, `blank` |
 
-### Managing Values
-
-When editing a resource (e.g., a product), metafields appear in a dedicated section. The admin panel automatically builds forms for all defined metafields.
-
-To set a value programmatically, use the resource's nested `customFields` accessor (parent ID first):
-
-
-```typescript Admin SDK
-await client.products.customFields.create('prod_xxx', {
-  custom_field_definition_id: 'cfdef_xxx',
-  value: 'Wilson',
-})
-```
+Use `i_cont` for case-insensitive matching. A comparison that doesn't suit the field's type is ignored rather than rejected, so a stale filter in a saved view can't break a page.
 
-```bash CLI
-spree api post /products/prod_xxx/custom_fields -d '{
-  "custom_field_definition_id": "cfdef_xxx",
-  "value": "Wilson"
-}'
-```
+> **INFO:** If you use Meilisearch, re-index after changing these flags so the new fields are picked up. Substring matching (`i_cont`, `cont`, `start`, `end`) is a database-provider feature; Meilisearch handles equality, ranges and presence. See [Search & Filtering](search-filtering.md).
 
+In the dashboard, fields with these flags become available in the product table's column picker, sort menu and filter panel — off by default, so merchants opt in per column.
 
-## Metafields vs Metadata
+## What can carry custom fields
 
-Spree has two permanent, complementary systems for custom data — **metadata for machines, metafields for humans**. They serve different purposes and are not interchangeable. Neither is going away.
+Most things you'd want to annotate: products, variants, orders, line items, customers, categories, payments, fulfillments, gift cards and store credits, among others.
 
-| Feature | Metafields | [Metadata](../customization/metadata.md) |
-|---------|-----------|----------|
-| **Purpose** | Merchant-defined structured attributes | Developer escape hatch — integration IDs, sync state |
-| **Schema** | Defined via MetafieldDefinitions | Schemaless JSON — no definition required |
-| **Validation** | Type-specific (text, number, boolean, etc.) | None — accepts any JSON-serializable data |
-| **Visibility** | Configurable (admin-only or public) | Write-only in Store API, readable in Admin API |
-| **Admin UI** | Dedicated management forms | JSON preview |
-| **Data Types** | 6 specific types | Any JSON value |
-| **Organization** | Namespaced (`namespace.key`) | Flat key-value structure |
-| **Queryable** | Via SQL joins, Ransack scopes, search providers | Via JSONB operators (PostgreSQL) |
+## Custom fields or metadata?
 
-**Use Metafields** when you need type validation, visibility control, admin UI forms, or organized namespacing.
+Spree has two ways to store your own data, and they are not competing — they solve different problems.
 
-**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.
+| | Custom fields | [Metadata](../customization/metadata.md) |
+|---|---|---|
+| **For** | Data a merchant curates | Data your code keeps |
+| **Shape** | Declared and typed | Any JSON, no declaration |
+| **Dashboard** | Proper edit forms | Raw JSON |
+| **Visibility** | Configurable per field | Never read by the Store API |
+| **Searchable** | Yes, opt in | Not through the product search |
 
-> **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).
+Put it simply: **custom fields are for people, metadata is for machines.** If a merchant should type it, define a custom field. If it is a sync token or an external ID that only your integration reads, use metadata.
 
-## Related Documentation
+## Related
 
-- [Metadata](../customization/metadata.md) — Simple key-value metadata
-- [Products](products.md) — Product catalog
-- [Events](events.md) — Subscribe to metafield events
-- [Admin SDK](../sdk/admin/resources.md) — Manage definitions and values from TypeScript
+- [Metadata](../customization/metadata.md) — the machine-readable alternative
+- [Products](products.md) — the most common place for custom fields
+- [Search & Filtering](search-filtering.md) — how filters and search work
+- [Admin SDK](../sdk/admin/resources.md) — managing definitions and values in TypeScript

package/dist/developer/core-concepts/order-totals.md

@@ -0,0 +1,110 @@
+---
+title: Order Totals
+description: How an order total is built up from items, tax, discounts, delivery and fees — and how to render a summary that adds up.
+---
+
+## Overview
+
+An order total is rarely just the sum of the item prices. Tax is added or already inside them, a promo code takes something off, delivery costs something, gift wrapping costs a bit more.
+
+Spree records each of those as its own kind of row, and keeps a running total for each kind on the order itself. That means the summary block in your checkout is a handful of fields — you don't add anything up yourself.
+
+```mermaid
+flowchart TB
+    Items["Item total"] --> Total["Order total"]
+    Discounts["Discounts"] --> Total
+    Delivery["Delivery"] --> Total
+    Fees["Fees"] --> Total
+    Tax["Tax"] --> Total
+
+    style Total fill:#e8f5e9,stroke:#2e7d32
+```
+
+## The totals
+
+```typescript Store SDK
+const order = await client.orders.get('or_xxx')
+
+order.display_item_total     // "$120.00"  items, before tax and discounts
+order.display_discount_total // "-$12.00"  everything taken off
+order.display_delivery_total // "$5.00"    delivery
+order.display_fee_total      // "$2.50"    surcharges
+order.display_tax_total      // "$22.60"   all tax
+order.display_total          // "$138.10"  what the customer pays
+```
+
+| Attribute | What it sums |
+|---|---|
+| `item_total` | Line item prices, before tax and discounts |
+| `discount_total` | Every [discount](discounts.md) |
+| `delivery_total` | Delivery charges |
+| `fee_total` | Every [fee](fees.md) |
+| `tax_total` | All [tax](taxes.md) |
+| `included_tax_total` | Tax already inside the displayed prices |
+| `additional_tax_total` | Tax added on top |
+| `total` | What the customer pays |
+| `amount_due` | Still to pay, after gift cards and store credit |
+
+## Two forms of every amount
+
+Every total comes twice: `total` is the raw value, `display_total` is formatted for the order's currency.
+
+```json
+{
+  "total": "138.10",
+  "display_total": "$138.10"
+}
+```
+
+**Render the `display_` one.** It knows the currency symbol, which side it goes on, and which separator that locale uses — `$138.10`, `138,10 €`, `¥138`. Formatting it yourself means reimplementing that, and getting it wrong for somebody.
+
+> **NOTE:** Money is a **string**, never a number. JavaScript can't represent every decimal exactly: `0.1 + 0.2` gives `0.30000000000000004`, which is not something you want inside a price.
+> 
+> If you must do arithmetic, use a decimal library or work in whole cents. Most of the time you don't need to — Spree already did it.
+
+## The double-counting trap
+
+> **WARNING:** If you build a subtotal yourself, include `additional_tax_total` only — never `included_tax_total`.
+> 
+> Included tax is **already inside** the item prices. Adding it again charges the customer's eyes twice, and produces a summary that doesn't match the amount taken from their card. This is the single most common bug in a European storefront.
+
+The two exist because the same order can carry both: VAT already inside the goods, and a separately-added tax on something else. `tax_total` covers both, which is why it's the safe field to display on its own line.
+
+## Totals update themselves
+
+Every change to a cart returns the whole cart, totals included:
+
+```typescript Store SDK
+const cart = await client.carts.items.create(cartId, {
+  variant_id: 'var_xxx',
+  quantity: 2,
+})
+
+cart.display_total // already correct
+```
+
+There is never a second "recalculate" request to make, and never a moment where the summary on screen disagrees with what the server thinks. Adding an item, entering an address, applying a code — each response carries the new numbers.
+
+The totals are worked out again at the moment the cart is completed, so a price that changed while the customer sat on the review page can't lead to the wrong charge.
+
+## Once an order is placed
+
+The rows stop being regenerated. Editing a placed order re-adds the rows it already has rather than starting over, so today's promotions and rates can't rewrite what a customer agreed to last week.
+
+## Where each row attaches
+
+The individual rows are there if you need them — an itemised invoice, a tax report:
+
+- **[Tax lines](taxes.md)** → a line item, a fulfillment, or a fee
+- **[Discounts](discounts.md)** → a line item or a fulfillment
+- **[Fees](fees.md)** → a line item, a fulfillment, or the order itself
+
+Each row also keeps a copy of where it came from — the rate and label on a tax line, the code and promotion on a discount. If someone deletes that promotion next month, the order still says what the customer was actually given.
+
+## Related
+
+- [Taxes](taxes.md) — how tax is worked out
+- [Discounts](discounts.md) — money off
+- [Fees](fees.md) — surcharges and duties
+- [Carts](carts.md) — checkout and completion
+- [Orders](orders.md) — the placed order

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

@@ -148,7 +148,7 @@ Where admin edits are allowed, totals are re-added from the order's existing row
 
 ## Money on an order
 
-Tax, discounts and fees are kept as separate records, so you can ask what tax was charged without picking through a mixed list. See [Taxes, Discounts & Fees](taxes-discounts-fees.md).
+Tax, discounts and fees are kept as separate records, so you can ask what tax was charged without picking through a mixed list. See [Order totals](order-totals.md).
 
 ## Events
 

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

@@ -1,5 +1,6 @@
 ---
 title: Payments
+description: Taking money — payment methods, payment sessions, saved cards, refunds, and how a payment finishes reliably even when a customer closes the tab.
 ---
 
 ## Overview
@@ -98,7 +99,7 @@ erDiagram
     CreditCard }o--|| Customer : "belongs to"
     StoreCredit }o--|| Customer : "belongs to"
     Refund }o--|| Payment : "belongs to"
-    Refund }o--|| Reimbursement : "belongs to"
+    Refund }o--o| Return : "may come from"
 ```
 
 **Key relationships:**
@@ -681,22 +682,18 @@ See [Events](events.md) for more details on subscribing to events.
 
 - [Payments (Store SDK)](../sdk/store/payments.md) - SDK how-to for payment sessions, payments, and setup sessions
 - [Build a Custom Payment Method](../how-to/custom-payment-method.md) - Step-by-step guide to creating your own payment gateway integration
-- [Orders](orders.md) - Order management and state machine
+- [Orders](orders.md) - Order lifecycle, payment and fulfillment status
 - [Checkout Customization](carts.md) - Customizing the checkout flow
 - [Events](events.md) - Subscribe to payment events
 
-## Key Services
+## Two paths to a completed order
 
-| Service | Description |
-|---------|-------------|
-| `Spree::Carts::Complete` | Completes the order — validates, processes payments (if not already done), advances state machine. Used by both the `POST /carts/:id/complete` endpoint and the webhook handler. |
-| `Spree::Payments::HandleWebhook` | Processes a normalized webhook event — creates Payment, marks session completed, calls `Carts::Complete`. |
-| `Spree::Payments::HandleWebhookJob` | Background job that wraps `HandleWebhook` — enqueued by the webhook controller for async processing. |
+A payment can finish in two places, and both have to end at the same result.
 
-Both `Carts::Complete` and `HandleWebhook` are registered in `Spree::Dependencies` and can be replaced with custom implementations:
+The customer's browser confirms the payment and your storefront completes the cart. Or the provider's own webhook arrives first — sometimes seconds later, sometimes because the customer closed the tab mid-redirect.
 
-```ruby
-# config/initializers/spree.rb
-Spree::Dependencies.carts_complete_service = 'MyApp::CustomCartComplete'
-Spree::Dependencies.payments_handle_webhook_service = 'MyApp::CustomWebhookHandler'
-```
+Whichever arrives first completes the order; the other finds the work already done and does nothing. That is what makes a closed tab or a flaky connection recoverable rather than a lost sale with a real charge attached.
+
+> **WARNING:** Never treat the browser returning from a redirect as proof of payment. The provider's webhook is the authoritative signal — a customer can close the tab, and a browser response can be forged.
+
+Both paths can be replaced if your integration needs different behaviour — see [Dependencies](../customization/dependencies.md).