@spree/docs 0.1.181 → 0.1.183

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.181",
+  "version": "0.1.183",
   "description": "Spree Commerce developer documentation for AI agents and local reference",
   "type": "module",
   "license": "CC-BY-4.0",

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