@spree/docs 0.1.182 → 0.1.183

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

@@ -1,134 +1,127 @@
 ---
 title: Translations
-description: Translate Spree products, taxons, and other store content into multiple languages using Mobility-backed translations and locale-aware APIs.
+description: Selling in more than one language — translating product content, and translating the interface around it.
 ---
 
 ## Overview
 
-Spree supports two types of translations:
+Two different things need translating, and they're handled separately because they belong to different people.
 
-1. **Resource Translations** — translatable content fields on models like Products, Taxons, and Stores (e.g., product name, description, slug)
-2. **UI Translations** — interface strings used in the admin panel (e.g., button labels, flash messages)
+**Your content** — product names, descriptions, category names — is written by whoever runs the store. Spree stores a version of each field per language.
 
-For configuring which locales and currencies are available in your store, see [Markets](markets.md). Markets control locale and currency assignment per geographic region.
+**The interface** — button labels, error messages, email wording — is written by Spree, and is already translated into dozens of languages by the community.
 
-## Resource Translations
+> **INFO:** Which languages a region gets is decided by its [Market](markets.md). A market sets the default locale alongside the currency, so a visitor from France lands on French prices and French copy without choosing anything.
 
-Resources with user-facing content fields have built-in support for translations. Each translatable resource has a corresponding translations table in the database — for example, product translations are stored in `spree_product_translations`.
+## Translating content
+
+Every translatable record keeps one row per language, so a product genuinely has a French name rather than a French name pasted over the English one.
 
 ```mermaid
 erDiagram
-    Product ||--o{ ProductTranslation : "has many"
-    Taxon ||--o{ TaxonTranslation : "has many"
-    Store ||--o{ StoreTranslation : "has many"
+    Product ||--o{ ProductTranslation : "one per locale"
 
     Product {
-        string id PK
         string status
+        string sku
     }
-
     ProductTranslation {
-        string id PK
-        string product_id FK
         string locale
         string name
-        text description
+        string description
         string slug
         string meta_title
-        string meta_description
-    }
-
-    TaxonTranslation {
-        string id PK
-        string taxon_id FK
-        string locale
-        string name
-        text description
-        string permalink
     }
 ```
 
-### Translatable Fields
+### What can be translated
 
-| Resource         | Translatable Fields                                                                                                                                                                 |
-| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Product          | `name`, `description`, `slug`, `meta_description`, `meta_title`                                                                                                             |
-| Taxon            | `name`, `description`, `permalink`                                                                                                                                                        |
-| Taxonomy         | `name`                                                                                                                                                                                |
-| Option Type      | `presentation`                                                                                                                                                                  |
-| Option Value     | `presentation`                                                                                                                                                                  |
-| Property         | `presentation`                                                                                                                                                   |
-| Product Property | `value`                                                                                                                                                                 |
-| Store            | `name`, `meta_description`, `meta_keywords`, `seo_title`, `customer_support_email`, `address`, `contact_phone` |
+| Resource | Fields |
+|---|---|
+| Product | `name`, `description`, `slug`, `meta_title`, `meta_description` |
+| Category | `name`, `description`, `permalink` |
+| Collection | `name`, `description`, `permalink` |
+| Product type | `name` |
+| Option type | `presentation` |
+| Option value | `presentation` |
+| Store | `name`, `seo_title`, `meta_description`, `meta_keywords`, and support contact details |
+| Policy | `name`, `body` |
+| Seller | `name`, `about` |
 
-### Store API
+Note that **slugs are translated too**. A French page can live at `/produits/sac-spree` rather than at the English slug with French words on it — which is what search engines actually reward. See [Slugs](slugs.md#internationalization).
 
-To retrieve translated content, pass the locale via the [`X-Spree-Locale` header](../../api-reference/store-api/localization.md) or the SDK `locale` option:
+## Reading translated content
+
+Ask for a locale and you get that language back. Nothing else about the request changes:
 
 
 ```typescript Store SDK
-// Fetch product in French
-const product = await client.products.get('spree-tote', {}, {
-  locale: 'fr',
-})
+const product = await client.products.get('spree-tote', {}, { locale: 'fr' })
 
 product.name        // "Sac Spree"
-product.description // "Un sac fourre-tout élégant..."
+product.description // "Un sac fourre-tout élégant…"
 product.slug        // "sac-spree"
 
-// List categories in German
-const { data: categories } = await client.categories.list({}, {
-  locale: 'de',
-})
+const { data: categories } = await client.categories.list({}, { locale: 'de' })
 ```
 
 ```typescript Admin SDK
-// Pass the locale as a request option to get translated content.
-// The Admin API resolves by prefixed ID only — slugs are not accepted.
+// The Admin API resolves by ID only — slugs are not accepted here
 const product = await adminClient.products.get('prod_86Rf07xd4z', {}, { locale: 'fr' })
-
-const { data: categories } = await adminClient.categories.list({}, { locale: 'de' })
 ```
 
 ```bash cURL
-# Fetch product in French
 curl 'https://api.mystore.com/api/v3/store/products/spree-tote' \
   -H 'X-Spree-API-Key: pk_xxx' \
   -H 'X-Spree-Locale: fr'
 ```
 
 
-Slugs are also localized — a product can have different slugs per locale. See [Slugs](slugs.md#internationalization) for details.
+If a field has no translation for the requested locale, you get the default-language value rather than an empty string — a half-translated catalogue still renders as a usable page.
+
+> **NOTE:** Responses vary by locale, so if you cache them, include the locale in the cache key. Spree sets `Vary` headers for you, which is enough for a CDN but not for a hand-rolled in-memory cache.
+
+## Writing translations
 
-### Managing Translations
+Merchants translate in the dashboard, switching locale on the record they're editing. For bulk work — handing a catalogue to a translation agency — export to CSV, translate, and import it back.
 
-Translations are managed in the Admin Panel. When editing a product, taxon, or other translatable resource, switch the locale selector to enter content in each language.
+Translations can also be written through the Admin API, which is what you'd use to sync from an external translation service:
 
-Translations can also be [managed via the Admin API](../sdk/admin/quickstart.md).
+```typescript Admin SDK
+await adminClient.products.update('prod_xxx', {
+  translations: {
+    fr: { name: 'Sac Spree', description: 'Un sac fourre-tout élégant…' },
+    de: { name: 'Spree Tasche' },
+  },
+})
+
+// Which resources and fields accept translations
+const { data: resources } = await adminClient.translatableResources.list()
+```
 
-## UI Translations
+Asking the API which resources are translatable means a translation tool doesn't need a hardcoded list that goes stale.
 
-Spree stores UI translation strings in a separate project: [Spree I18n](https://github.com/spree-contrib/spree_i18n). This is a community-maintained project with locale files for 43+ languages.
+## Translating the interface
 
-To install UI translations:
+Spree's own strings — everything in the dashboard and in transactional emails — come from a community-maintained project covering 40+ languages.
 
 
-```bash Spree CLI (Docker)
+```bash Spree CLI
 spree bundle add spree_i18n
 ```
 
-```bash Without Spree CLI
+```bash Bundler
 bundle add spree_i18n
 ```
 
 
-Once installed, all translation files are available automatically — no need to copy any files.
+That's the whole installation. Locales are picked up automatically; nothing needs copying into your app.
 
-> **INFO:** The full list of supported locales is available in the [Spree I18n GitHub repository](https://github.com/spree-contrib/spree_i18n/tree/main/config/locales).
+> **INFO:** See the [supported locales](https://github.com/spree-contrib/spree_i18n/tree/main/config/locales) in the Spree I18n repository. Contributions are welcome if yours is incomplete.
 
-## Related Documentation
+## Related
 
-- [Markets](markets.md) — Locale and currency configuration per geographic region
-- [Localization](../../api-reference/store-api/localization.md) — Locale, currency, and country headers in API requests
-- [Slugs](slugs.md) — Localized slugs and URL identifiers
-- [Products](products.md) — Product translations
+- [Markets](markets.md) — which locale and currency a region gets
+- [Slugs](slugs.md) — localized URLs
+- [Custom Fields](metafields.md) — translating your own fields
+- [Localization](../../api-reference/store-api/localization.md) — the locale, currency and country headers

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.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