@spree/docs 0.1.182 → 0.1.184

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

@@ -3,9 +3,6 @@ title: Webhooks
 description: Send real-time HTTP notifications to external services when events occur in your store.
 ---
 
-import { Since } from '/snippets/since.mdx';
-
-
 ## Overview
 
 Webhooks allow your Spree store to send real-time HTTP POST notifications to external services when events occur. When an order is completed, a product is updated, or inventory changes, Spree can automatically notify your CRM, fulfillment service, analytics platform, or any other system.
@@ -44,7 +41,7 @@ flowchart LR
     end
 ```
 
-1. An event is published (e.g., `order.completed`)
+1. An event is published (e.g., `order.placed`)
 2. The `WebhookEventSubscriber` receives all events
 3. It finds active webhook endpoints subscribed to that event
 4. For each endpoint, it creates a `WebhookDelivery` record and queues a job
@@ -107,13 +104,13 @@ The `subscriptions` attribute controls which events trigger webhooks to this end
 
 ```typescript Admin SDK
 await client.webhookEndpoints.update('whe_xxx', {
-  subscriptions: ['order.completed', 'order.canceled'],
+  subscriptions: ['order.placed', 'order.canceled'],
 })
 ```
 
 ```bash CLI
 spree api patch /webhook_endpoints/whe_xxx \
-  -d '{"subscriptions": ["order.completed", "order.canceled"]}'
+  -d '{"subscriptions": ["order.placed", "order.canceled"]}'
 ```
 
 
@@ -121,7 +118,7 @@ The `subscriptions` array accepts exact event names and wildcard patterns:
 
 | `subscriptions` value | Receives |
 |---|---|
-| `['order.completed', 'order.canceled']` | Only those two events |
+| `['order.placed', 'order.canceled']` | Only those two events |
 | `['order.*']` | All order events |
 | `['*.created']` | All creation events |
 | `['order.*', 'payment.*', 'shipment.shipped']` | Multiple patterns |
@@ -134,7 +131,7 @@ Each webhook delivery sends a JSON payload with the following structure. The `da
 ```json
 {
   "id": "550e8400-e29b-41d4-a716-446655440000",
-  "name": "order.completed",
+  "name": "order.placed",
   "created_at": "2025-01-15T10:30:00Z",
   "data": {
     "id": "or_m3Rp9wXz",
@@ -158,7 +155,7 @@ Each webhook delivery sends a JSON payload with the following structure. The `da
 | Field | Description |
 |-------|-------------|
 | `id` | Unique UUID for this event |
-| `name` | Event name (e.g., `order.completed`) |
+| `name` | Event name (e.g., `order.placed`) |
 | `created_at` | ISO8601 timestamp when event occurred |
 | `data` | Serialized resource data (V3 API format with [prefixed IDs](../../api-reference/introduction.md)) |
 | `metadata` | Additional context including Spree version |
@@ -175,7 +172,7 @@ Each webhook request includes these headers:
 |--------|-------------|
 | `Content-Type` | `application/json` |
 | `User-Agent` | `Spree-Webhooks/1.0` |
-| `X-Spree-Webhook-Event` | Event name (e.g., `order.completed`) |
+| `X-Spree-Webhook-Event` | Event name (e.g., `order.placed`) |
 | `X-Spree-Webhook-Signature` | HMAC-SHA256 signature for verification |
 | `X-Spree-Webhook-Timestamp` | Unix timestamp (seconds) generated at send time; included in the HMAC-SHA256 signed string as `{timestamp}.{payload}` and required to verify `X-Spree-Webhook-Signature` |
 
@@ -227,7 +224,7 @@ class WebhooksController < ApplicationController
     event = JSON.parse(request.body.read)
 
     case event['name']
-    when 'order.completed'
+    when 'order.placed'
       handle_order_completed(event['data'])
     when 'product.updated'
       handle_product_updated(event['data'])
@@ -271,7 +268,7 @@ await client.webhookEndpoints.deliveries.redeliver('whe_xxx', 'whd_xxx')
 ```
 
 ```bash CLI
-spree api get /webhook_endpoints/whe_xxx/deliveries -q event_name_eq=order.completed
+spree api get /webhook_endpoints/whe_xxx/deliveries -q event_name_eq=order.placed
 spree api post /webhook_endpoints/whe_xxx/deliveries/whd_xxx/redeliver
 ```
 
@@ -292,24 +289,9 @@ spree api post /webhook_endpoints/whe_xxx/deliveries/whd_xxx/redeliver
 
 ## Configuration
 
-### Enabling/Disabling Webhooks
-
-Webhooks are enabled by default. To disable globally:
+Webhooks are on by default and can be switched off installation-wide.
 
-```ruby
-# config/initializers/spree.rb
-Spree::Api::Config.webhooks_enabled = false
-```
-
-### SSL Verification
-
-SSL verification is enabled by default in production. In development, it's disabled to allow testing with self-signed certificates:
-
-```ruby
-# config/initializers/spree.rb
-Spree::Api::Config.webhooks_verify_ssl = true  # Force SSL verification
-Spree::Api::Config.webhooks_verify_ssl = false # Disable (not recommended for production)
-```
+SSL certificates are verified in production, and not in development — so you can point an endpoint at a local tunnel with a self-signed certificate while building. Both are configurable if your environment needs something different.
 
 ## Available Events
 
@@ -319,14 +301,16 @@ Common webhook events include:
 
 | Event | Description |
 |-------|-------------|
-| `order.completed` | Order checkout finished |
-| `order.canceled` | Order was canceled |
-| `order.paid` | Order is fully paid |
-| `shipment.shipped` | Shipment was shipped |
-| `payment.paid` | Payment was completed |
-| `product.created` | New product created |
-| `product.updated` | Product was modified |
-| `user.created` | New customer/user registered (the admin user class emits `admin.created`) |
+| `order.placed` | A customer completed checkout |
+| `order.paid` | The order is fully paid |
+| `order.canceled` | The order was canceled |
+| `order.shipped` | Everything on the order has shipped |
+| `fulfillment.shipped` | One parcel went out |
+| `payment.completed` | A payment succeeded |
+| `product.created` / `product.updated` | Catalog changes |
+| `product.out_of_stock` / `product.back_in_stock` | Availability flipped |
+| `customer.created` | A new customer registered |
+| `return.received` | A return arrived |
 
 ## Testing Webhooks
 
@@ -358,24 +342,6 @@ spree api post /webhook_endpoints/whe_xxx/send_test
 
 `send_test` delivers a synthetic `webhook.test` event so you can verify the endpoint is reachable and your signature-verification code works, without having to trigger a real order.
 
-### In Tests
-
-```ruby
-RSpec.describe 'Webhook delivery' do
-  let(:store) { create(:store) }
-  let(:endpoint) { create(:webhook_endpoint, store: store, subscriptions: ['order.completed']) }
-  let(:order) { create(:completed_order_with_totals, store: store) }
-
-  it 'delivers webhook when order completes' do
-    stub_request(:post, endpoint.url).to_return(status: 200)
-
-    expect {
-      order.publish_event('order.completed')
-    }.to have_enqueued_job(Spree::WebhookDeliveryJob)
-  end
-end
-```
-
 ## Best Practices
 
 
@@ -392,10 +358,10 @@ end
 
 ### Webhooks Not Delivering
 
-1. Check that webhooks are enabled: `Spree::Api::Config.webhooks_enabled`
-2. Verify the endpoint is active: `endpoint.active?`
-3. Confirm the endpoint subscribes to the event: `endpoint.subscribed_to?('order.completed')`
-4. Check the event has a `store_id` matching the endpoint's store
+1. Check that webhooks are enabled installation-wide
+2. Verify the endpoint is marked active
+3. Confirm the endpoint actually subscribes to the event you expect
+4. Check the event belongs to the same store as the endpoint
 
 ### Signature Verification Failing
 

package/dist/developer/how-to/custom-promotion.md

@@ -8,7 +8,7 @@ description: Step-by-step guide to creating custom promotion rules, discount act
 Spree's promotion system has three extension points:
 
 - **Rules** — conditions that decide when a promotion applies
-- **Actions** — what an applied promotion does, usually writing [Discount](../core-concepts/taxes-discounts-fees.md#discounts) rows
+- **Actions** — what an applied promotion does, usually writing [Discount](../core-concepts/discounts.md) rows
 - **Adjusters** — for discounts and fees that aren't promotions at all (loyalty pricing, gift wrap fees, payment surcharges)
 
 Spree ships with a comprehensive set of [built-in rules and actions](../core-concepts/promotions.md#rules). This guide shows how to build your own of each kind.
@@ -238,7 +238,7 @@ Like rules, registered actions surface automatically in the dashboard's promotio
 
 ## Custom Adjusters
 
-Not every charge or reduction is a promotion. A gift wrap fee, a payment surcharge, or loyalty pricing has no rules, no coupon codes, and no competition — it just needs to be on the order whenever it applies. That's an **adjuster**: a class invoked on every recalculation that owns a family of [Fee or Discount](../core-concepts/taxes-discounts-fees.md) rows.
+Not every charge or reduction is a promotion. A gift wrap fee, a payment surcharge, or loyalty pricing has no rules, no coupon codes, and no competition — it just needs to be on the order whenever it applies. That's an **adjuster**: a class invoked on every recalculation that owns a family of [Fee](../core-concepts/fees.md) or [Discount](../core-concepts/discounts.md) rows.
 
 ```ruby app/models/my_app/adjusters/gift_wrap.rb
 module MyApp
@@ -329,6 +329,6 @@ end
 ## Related Documentation
 
 - [Promotions](../core-concepts/promotions.md) — promotion architecture and built-in rules and actions
-- [Taxes, Discounts & Fees](../core-concepts/taxes-discounts-fees.md) — the typed rows actions and adjusters write
+- [Discounts](../core-concepts/discounts.md) and [Fees](../core-concepts/fees.md) — the rows actions and adjusters write
 - [Calculators](../core-concepts/calculators.md) — available calculator types for promotion actions
 - [Events](../core-concepts/events.md) — subscribe to promotion events

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spree/docs",
-  "version": "0.1.182",
+  "version": "0.1.184",
   "description": "Spree Commerce developer documentation for AI agents and local reference",
   "type": "module",
   "license": "CC-BY-4.0",

package/dist/developer/core-concepts/companies-and-catalogs.md

@@ -1,81 +0,0 @@
----
-title: Companies & Catalogs
-description: How Spree models B2B buyer organizations — a multi-level company tree with members and an address book — and the catalogs that decide what each audience sees and pays.
----
-
-## Overview
-
-A business customer in Spree is a **tree of company nodes**, not a flat account. One node can stand alone — a company with a few members and addresses — or grow into a group: subsidiaries, divisions, regional units, each with its own buyers and ship-to sites.
-
-```mermaid
-erDiagram
-    Company ||--o{ Company : "parent of"
-    Company ||--o{ CompanyMembership : "has many"
-    Company ||--o{ CompanyAddress : "has many"
-    Company ||--o{ CompanyInvitation : "has many"
-    Company ||--o{ TaxIdentifier : "legal entities only"
-    Company ||--o{ TaxExemptionCertificate : "legal entities only"
-
-    Company {
-        string name
-        string kind "company | division"
-        string external_id
-    }
-    CompanyMembership {
-        string role "cosmetic label"
-    }
-    CompanyAddress {
-        string label
-        boolean default_billing
-        boolean default_shipping
-    }
-    CompanyInvitation {
-        string email
-        string token
-        datetime expires_at
-    }
-```
-
-Three ideas carry the whole model:
-
-- **The tree is structure.** `Spree::Company` is self-referential (`parent_id`), store-scoped, and shallow — depth is capped at five levels. How many ship-to sites a node has never dictates how many nodes exist; addresses are just an address book.
-- **Nodes are typed, and the type decides tax.** A `company` node is a legal entity; a `division` is an organizational unit. Tax registrations and exemption certificates exist only on legal entities, and a purchase's tax always resolves through the node's `legal_entity` — for a `company` that is the node itself, and for a `division` it is its nearest `company` ancestor, whose registrations then cover the division's purchases. The walk stops at that first `company` node whether or not it holds any registration, so a subsidiary with no VAT number of its own has none — it never borrows its parent's.
-- **Membership is standing over a subtree.** A `CompanyMembership` joins a customer to a node, and that standing covers the node and everything below it. Any authorization question — "may this customer act for node N?" — is a membership check on N and its ancestors, never an equality check on one node.
-
-## Members and invitations
-
-People join by email, from either side — staff in the dashboard or an existing member on the storefront. An email that matches a store customer becomes a membership immediately; an unknown email becomes a `Spree::CompanyInvitation` — a plaintext-token record with a 30-day expiry, whose invite email links to the storefront acceptance page. Accepting either registers a new account (through the standard customer-creation flow, with the invited email) or binds the invitation to the signed-in customer, and lands as a membership either way.
-
-Memberships stay always-active and always customer-backed: the pending state lives on the invitation, never as a status on the membership.
-
-**In open source, every member can do everything within their standing** — buy, see the subtree's purchases, manage addresses and members. There are no company roles; the `role` string on a membership is a cosmetic label. Finer control (roles, approvals, spending limits) is an Enterprise layer that enforces through the storefront access policy class (`Spree::Dependencies.storefront_access_policy_class`) and the checkout `validate` hooks — injection points that are deliberate no-ops in OSS.
-
-## Purchases
-
-Carts and orders carry a `company_id` pointing at any node — buying *for* a division means pointing at it. A buyer with exactly one membership resolves to it automatically; a buyer with several names the node on their cart (the `company_id` param on cart update, validated against their standing). The node is frozen onto the order at completion, like every other order attribute, so a placed order's tax treatment stays explainable no matter how the tree changes later.
-
-Exemption certificates and the company's tax registration always resolve through `company.legal_entity` — see [Taxes, Discounts & Fees](/docs/developer/core-concepts/taxes-discounts-fees) for how they reach the tax provider.
-
-## Catalogs
-
-A `Spree::Catalog` narrows what an audience sees and — through an optional price list — what they pay.
-
-```mermaid
-erDiagram
-    Catalog ||--o{ CatalogProduct : "assortment"
-    Catalog ||--o{ CatalogAssignment : "audiences"
-    Catalog }o--o| PriceList : "optional pricing"
-    CatalogAssignment }o--|| Company : "or"
-    CatalogAssignment }o--|| CustomerGroup : "or"
-    CatalogAssignment }o--|| Market : "or"
-    CatalogAssignment }o--|| Channel : "or"
-```
-
-- **Assortment** — a positioned product join, and the switch between a catalog's two modes. A *curated* assortment restricts: the audience sees only what's in it. An *empty* assortment is a pricing-only overlay: the attached price list applies and nothing is hidden — which is how "everyone sees the public store, this company just gets special prices" is expressed. An explicit import action copies the price list's products into the assortment when a restrictive catalog should start from the priced range.
-- **Audiences** — assignments to a channel, a customer group, a market, or a company node. A company assignment covers the node's **subtree**: assign the group-wide catalog once at the root, and a branch adds its own extra catalog without re-assigning the shared one.
-- **Visibility** — a buyer resolving to a company node sees the union of the effective catalogs on the node and its ancestors; otherwise their customer group's catalogs apply; otherwise every channel listing (narrowed to the channel's default catalog when one is set). Any effective catalog with an empty assortment lifts the restriction — the union then includes the whole range. Gated storefront access runs first — a login-gated guest never reaches this resolution.
-- **Pricing** — the effective catalogs' price lists are checked nearest node first (the purchase node's own assignments before its parent's), then the ordinary rule-matched price lists, then base prices. A price list attached to a catalog applies *because the catalog applies* — its own rules are not consulted, and it is excluded from generic rule matching so a rule-less list cannot leak to every shopper.
-
-## Storefront self-service
-
-The Store API ships a full company directory for members: their memberships with ancestor paths (`GET /store/account/companies`), node details and renaming, the address book, members and invitations, and the subtree's completed orders. Authorization on every endpoint is **standing plus the access policy** — never roles, never CanCanCan. The deliberate trade-off: within a company, OSS trusts every member; merchants who need restraint layer the Enterprise governance on the same injection points, with no schema changes.

package/dist/developer/core-concepts/taxes-discounts-fees.md

@@ -1,199 +0,0 @@
----
-title: Taxes, Discounts & Fees
-description: How Spree records money added to or taken off an order — separate tax lines, discounts and fees, and the order totals you render in a storefront.
----
-
-## Overview
-
-An order total is rarely just the sum of item prices. Tax gets added, a promo code takes something off, gift wrapping costs extra. Spree records each of those as its own row, of one of three kinds:
-
-| Kind | Effect | What it is |
-|---|---|---|
-| **Tax line** | adds | Tax charged on an item, on delivery, or on a fee |
-| **Discount** | subtracts | A promotion or a manual reduction |
-| **Fee** | adds | A surcharge — handling, gift wrap, cash on delivery |
-
-Keeping them apart means a direct question gets a direct answer. "What tax did we charge on this order?" is one request against tax lines, rather than filtering a mixed list and hoping you caught every case.
-
-```mermaid
-erDiagram
-    Order ||--o{ TaxLine : "has many"
-    Order ||--o{ Discount : "has many"
-    Order ||--o{ Fee : "has many"
-    LineItem ||--o{ TaxLine : "taxed by"
-    LineItem ||--o{ Discount : "reduced by"
-    Fulfillment ||--o{ TaxLine : "taxed by"
-    Fee ||--o{ TaxLine : "taxed by"
-
-    TaxLine {
-        string label
-        string rate
-        boolean included
-        string amount
-    }
-    Discount {
-        string label
-        string kind
-        string code
-        string amount
-    }
-    Fee {
-        string label
-        string kind
-        string amount
-    }
-```
-
-> **NOTE:** Money is sent as a **string** — `"15.99"`, not `15.99`. JavaScript numbers can't represent every decimal exactly, and `0.1 + 0.2` gives `0.30000000000000004`, which is not something you want inside a total. If you need to do arithmetic, use a decimal library or work in whole cents.
-
-## Building an order summary
-
-Most storefronts never need the individual rows. The order already carries a total for each kind, so you can render a summary directly:
-
-```typescript
-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_tax_total       // "$22.60"   all tax
-order.display_total           // "$135.60"  what the customer pays
-```
-
-Every total comes in two forms: `total` is the raw value (`"135.60"`) and `display_total` is formatted for the order's currency (`"$135.60"`). Render the `display_` one — it handles the symbol, decimal separator and where the symbol goes.
-
-| Attribute | What it sums |
-|---|---|
-| `item_total` | Line item prices before tax and discounts |
-| `discount_total` | All discounts |
-| `tax_total` | All tax |
-| `included_tax_total` | Tax already inside displayed prices |
-| `additional_tax_total` | Tax added on top |
-| `delivery_total` | Delivery charges |
-| `total` | What the customer pays |
-
-> **WARNING:** If you add up a subtotal yourself, include `additional_tax_total` only. `included_tax_total` is **already inside** the item prices — adding it again counts the tax twice. This is the most common mistake when building a European storefront.
-
-## Tax lines
-
-A tax line records one tax charge and what it was charged on.
-
-| Attribute | Description |
-|---|---|
-| `label` | What the customer sees, e.g. `VAT 20%` |
-| `rate` | The rate applied, e.g. `"0.2"` |
-| `included` | Whether the tax was already inside the displayed price |
-| `amount` / `display_amount` | Tax charged |
-| `line_item_id` / `fulfillment_id` / `fee_id` | What was taxed — exactly one is set |
-| `tax_rate_id` | The configured rate, when tax came from Spree rather than an outside service |
-
-`included` is the field that trips people up. In most of Europe a €120 price already contains €20 of VAT, so the tax line is there for information — the customer pays €120, not €140. In the US, tax is added at checkout, so the same field is `false` and the amount really is extra.
-
-```typescript Admin SDK
-const taxLines = await adminClient.orders.taxLines.list('or_xxx')
-```
-
-You never create tax lines yourself. They're written whenever the order total is worked out — see [Taxes](taxes.md).
-
-## Discounts
-
-| Attribute | Description |
-|---|---|
-| `label` | What the customer sees, e.g. `Summer Sale` |
-| `kind` | `promotion` or `manual` |
-| `code` | The coupon code used, if any |
-| `value` / `value_type` | The rule behind it, e.g. `"10"` / `percent`. Accepts a string or a number on write. |
-| `amount` / `display_amount` | The reduction, as a negative amount |
-| `promotion_id` | The promotion it came from |
-| `line_item_id` / `fulfillment_id` | What it reduced |
-
-Most discounts come from [Promotions](promotions.md) — a customer applies a code and the rows appear. A **manual** discount is one an admin adds directly, for a goodwill gesture or a price match:
-
-
-```typescript Admin SDK
-// 10% off a single line item
-await adminClient.orders.discounts.create('or_xxx', {
-  label: 'Goodwill discount',
-  value: '10',
-  value_type: 'percent',
-  line_item_id: 'li_xxx',
-})
-
-// A flat amount across the order
-await adminClient.orders.discounts.create('or_xxx', {
-  label: 'Price match',
-  value: '15.00',
-  value_type: 'flat',
-})
-```
-
-```bash cURL
-curl -X POST 'https://api.mystore.com/api/v3/admin/orders/or_xxx/discounts' \
-  -H 'X-Spree-API-Key: sk_xxx' \
-  -H 'Content-Type: application/json' \
-  -d '{ "label": "Goodwill discount", "value": 10, "value_type": "percent" }'
-```
-
-
-Only manual discounts can be edited or deleted. Changing one that came from a promotion returns a `422` — those belong to the promotion that created them, and letting an order disagree with its own promotion is how reporting stops adding up.
-
-A discount on the whole order is shared out across the items rather than kept as one lump sum. So if the customer later returns one item, Spree knows how much of the discount belonged to it.
-
-## Fees
-
-| Attribute | Description |
-|---|---|
-| `label` | What the customer sees, e.g. `Gift wrapping` |
-| `kind` | `surcharge`, `handling`, `gift_wrap`, `cod`, `payment`, `duty`, or your own |
-| `amount` / `display_amount` | The charge |
-| `line_item_id` / `fulfillment_id` | What it applies to — both empty means the whole order |
-
-```typescript Admin SDK
-await adminClient.orders.fees.create('or_xxx', {
-  label: 'Gift wrapping',
-  kind: 'gift_wrap',
-  amount: '5.00',
-  line_item_id: 'li_xxx',
-})
-```
-
-Fees are always positive, and they're taxable by default — a fee can have its own tax lines. Customs duties are the one exception, described below. To take money off, create a discount instead. That way a refund never has to work out whether a negative fee was a charge or a credit.
-
-### Customs duties
-
-A `duty` fee is the one kind tax is **not** applied to automatically. A customs duty is an import charge levied by the destination country, not a sale that domestic tax applies to, so charging tax on top of it would invent tax the merchant never owed. Where import VAT is charged on a duty, whoever calculates the duty records that tax itself.
-
-A duty also keeps a copy of what it was calculated from — the HS code, the country of origin, the rate — in its `metadata`. Classification on a product can change next month; what the customer was charged must not.
-
-## Where rows attach
-
-Each row points at exactly the thing it applies to:
-
-- **Tax lines** → a line item, a [fulfillment](fulfillments.md), or a fee, so item tax and delivery tax stay separately visible
-- **Discounts** → a line item or a fulfillment
-- **Fees** → a line item, a fulfillment, or the order itself
-
-Rows also keep a copy of where they 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.
-
-## When totals change
-
-Totals are worked out again whenever something changes on a cart — an item added, an address entered, a code applied. The response to every cart change already includes the new totals, so a follow-up request is never needed:
-
-```typescript
-// The returned cart already has updated totals
-const cart = await client.carts.items.create(cartId, {
-  variant_id: 'var_xxx',
-  quantity: 2,
-})
-
-cart.display_total // already correct
-```
-
-Once an order is placed, the rows stop being regenerated. Editing a placed order re-adds its existing rows rather than starting from scratch, so today's promotions can't quietly rewrite what a customer agreed to last week.
-
-## Related
-
-- [Taxes](taxes.md) — how tax is worked out
-- [Promotions](promotions.md) — where most discounts come from
-- [Fulfillments](fulfillments.md) — delivery charges
-- [Orders](orders.md) — order totals and statuses