@spree/docs 0.1.181 → 0.1.183

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

@@ -1,163 +1,175 @@
 ---
 title: Taxes
-description: Tax categories, tax rates, zones, and how Spree calculates taxes at checkout
+description: How Spree works out tax — tax categories and rates, inclusive versus added-on pricing, and connecting an external tax service.
 ---
 
 ## Overview
 
-Spree uses Tax Categories and Tax Rates to calculate taxes for orders. Products are assigned to tax categories, and tax rates define the percentage charged within specific geographic [Zones](addresses.md#zones).
+Tax is the part of commerce most likely to differ from what you assumed. A US shopper expects `$17.99` on the shelf and a little more at the till. A German shopper expects `€17.99` to be the whole story, VAT already inside it. Both are correct, and a store selling to both has to do both.
+
+Spree handles this by keeping three things separate:
+
+- **What is being sold** — a [tax category](#tax-categories) groups products taxed the same way
+- **Where the customer is** — their [market](markets.md) and shipping address
+- **Who works out the number** — Spree's own rates, or an external tax service
+
+The result of all this is a set of **tax lines** on the order — one per charge, recording what was taxed and at what rate. This page is about how they get their numbers.
 
 ```mermaid
-erDiagram
-    TaxCategory ||--o{ TaxRate : "has many"
-    TaxCategory ||--o{ Product : "has many"
-    TaxRate }o--|| Zone : "applies in"
-    TaxRate ||--o{ Adjustment : "creates"
-    Zone ||--o{ ZoneMember : "has many"
-
-    TaxCategory {
-        string name
-        boolean is_default
-        string tax_code
-    }
-
-    TaxRate {
-        string name
-        decimal amount
-        boolean included_in_price
-    }
-
-    Zone {
-        string name
-        string kind
-    }
+flowchart LR
+    Product -->|"has a"| TaxCategory
+    Address -->|"determines"| Market
+    Market -->|"selects"| Provider["Tax provider"]
+    TaxCategory --> Provider
+    Provider -->|"writes"| TaxLine["Tax lines on the order"]
 ```
 
-**Key relationships:**
-- **Tax Category** groups products for tax purposes (e.g., "Clothing", "Food", "Digital")
-- **Tax Rate** defines the percentage and rules for a Tax Category within a [Zone](addresses.md#zones)
-- **Zone** defines geographic regions (countries or states) where taxes apply
-- **[Adjustments](taxes-discounts-fees.md)** are created on orders/line items to apply taxes
+## Tax categories
 
-## Tax Categories
+A tax category is how you say "these things are taxed alike". Children's clothing, books and hot food are treated differently from general goods in many countries, and a tax category is where that distinction lives.
 
-Tax categories group products by how they're taxed. Common examples:
+Every product carries one. If you don't choose, the default is used.
 
-- **Clothing** — standard tax rate
-- **Food** — reduced or exempt rate
-- **Digital** — different rules per jurisdiction
+| Field | Description | Example |
+|---|---|---|
+| `name` | What it's called | `Standard`, `Reduced`, `Digital` |
+| `is_default` | Used by products that don't pick one | `true` |
+| `tax_code` | The code your tax service knows it by | `1257L` |
 
-Each product is assigned a tax category. One category can be set as the default for products that don't have an explicit assignment.
+```typescript Admin SDK
+const reduced = await adminClient.taxCategories.create({
+  name: 'Reduced rate',
+  tax_code: '1257L',
+})
+```
 
-| Attribute | Description | Example |
-|-----------|-------------|---------|
-| `name` | Category name | `Clothing` |
-| `is_default` | Whether this is the default category | `true` |
-| `tax_code` | Code from your tax provider (e.g., Stripe, Avalara) | `1257L` |
+`tax_code` matters once you connect an external service — it is how you tell that service what kind of thing this is, in the vocabulary it already uses.
 
-Manage tax categories via the [Admin API](../../api-reference/admin-api/introduction.md), using the [Admin SDK resource clients](../sdk/admin/resources.md):
+## Tax rates
 
+A tax rate is the number itself, plus where it applies and whether it's already in the price.
 
-```typescript Admin SDK
-import { createAdminClient } from '@spree/admin-sdk'
+| Field | Description | Example |
+|---|---|---|
+| `name` | What appears on the invoice | `VAT 20%` |
+| `amount` | The rate as a decimal | `0.2` for 20% |
+| `included_in_price` | Whether the price already contains it | `true` in the EU |
+| `country_code` / `state_code` | Where it applies | `DE`, or `US` + `CA` |
+| `tax_category` | What it applies to | `Standard` |
 
-const client = createAdminClient({
-  baseUrl: 'https://store.example.com',
-  secretKey: 'sk_xxx',
+```typescript Admin SDK
+const { data: rates } = await adminClient.taxRates.list()
+
+await adminClient.taxRates.create({
+  name: 'VAT 20%',
+  amount: '0.2',
+  included_in_price: true,
+  country_code: 'GB',
+  tax_category_id: 'taxcat_xxx',
 })
+```
 
-const clothing = await client.taxCategories.create({
-  name: 'Clothing',
-  tax_code: '1257L',
-  is_default: true,
-})
+Rates name their country and state by **ISO code**, not by an ID — `DE`, `US` + `CA`. There's no separate region record to create first.
 
-await client.taxCategories.update('taxcat_xxx', { is_default: false })
-await client.taxCategories.delete('taxcat_xxx')
-```
+## Included or added on
 
-```bash CLI
-spree api post /tax_categories -d '{"name": "Clothing", "tax_code": "1257L", "is_default": true}'
-spree api get /tax_categories
-```
+`included_in_price` is the single most consequential setting here, so it's worth being precise about what it does.
 
+**Added on (US style):**
 
-## Tax Rates
+The shelf price is what the product costs. Tax is worked out at checkout, once the address is known, and added.
 
-Tax rates define the percentage charged for a specific tax category within a geographic zone.
+    A $17.99 item at 5%:
 
-| Attribute | Description | Example |
-|-----------|-------------|---------|
-| `name` | Rate name | `California Sales Tax` |
-| `amount` | Tax percentage as a decimal | `0.08` (8%) |
-| `included_in_price` | Whether tax is included in the displayed price | `false` |
-| `zone` | Geographic region where this rate applies | `US` |
-| `tax_category` | Products this rate applies to | `Clothing` |
+    | | |
+    |---|---|
+    | Price shown | **$17.99** |
+    | Tax added | $0.90 |
+    | Customer pays | **$18.89** |
 
-## Tax Types
+    Set `included_in_price: false`.
 
-### Sales Tax (tax-exclusive)
+  **Included (EU style):**
 
-Common in the United States. The displayed price does **not** include tax — tax is added at checkout based on the shipping address.
+The shelf price is the whole price. The tax inside it is shown for information — the customer pays the number they saw.
 
-**Example:** A $17.99 item with 5% sales tax:
-- Displayed price: **$17.99**
-- Tax at checkout: **$0.90**
-- Order total: **$18.89**
+    A £17.99 item at 20% VAT:
 
-### Value Added Tax / VAT (tax-inclusive)
+    | | |
+    |---|---|
+    | Price shown | **£17.99** |
+    | VAT inside it | £3.00 |
+    | Customer pays | **£17.99** |
 
-Common in Europe and many other countries. The displayed price **already includes** tax. When shipping outside the tax zone, the tax is removed from the price.
+    Set `included_in_price: true`.
 
-**Example:** A £17.99 item with 5% VAT included:
-- Displayed price: **£17.99** (includes £0.86 VAT)
-- If shipped outside VAT zone: price reduces to **£17.13**
 
-> **INFO:** The `tax_inclusive` setting on [Markets](markets.md) controls whether prices are displayed with or without tax for each geographic region.
+> **WARNING:** When building an order summary, add `additional_tax_total` only. `included_tax_total` is **already inside** the item prices — adding it counts the tax twice. This is the most common bug in a European storefront.
 
-## Default Tax Zone
+Because prices are shown before anyone knows where the shopper lives, each [Market](markets.md) declares whether its prices are quoted with tax included. That's what lets a catalogue page show honest prices to a German visitor and a US visitor at the same time.
 
-Spree uses a default tax zone to estimate taxes before the customer enters a shipping address. This is important for stores with tax-inclusive pricing (VAT) — it determines which tax rate is assumed in the displayed price.
+## Tax lines
 
-If the customer's shipping address is outside the default tax zone, the assumed tax is removed and the correct rate for their zone is applied.
+Whatever works out the tax, the record is the same: a tax line per charge, saying what was taxed and how.
 
-## Tax Calculation at Checkout
+| Attribute | Description |
+|---|---|
+| `label` | What the customer sees — `VAT 20%` |
+| `rate` | The rate applied — `"0.2"` |
+| `included` | Whether the tax was already inside the displayed price |
+| `amount` / `display_amount` | The tax charged |
+| `line_item_id` / `fulfillment_id` / `fee_id` | What was taxed — exactly one is set |
 
-During checkout, taxes are calculated based on the shipping address:
+```typescript Admin SDK
+const { data: taxLines } = await adminClient.orders.taxLines.list('or_xxx')
+```
 
-1. The customer's shipping address determines their [Zone](addresses.md#zones)
-2. Spree finds matching tax rates for that zone and the product's tax category
-3. Tax [Adjustments](taxes-discounts-fees.md) are created on line items
-4. The order total is updated
+Tax lines attach to a line item, a [fulfillment](fulfillments.md), or a [fee](fees.md) — so tax on goods and tax on delivery stay separately visible, which is what a tax return needs.
 
-> **NOTE:** For complex tax requirements (interstate US sales, international VAT), consider using automated tax calculation. The [Stripe Tax integration](../../integrations/payments/stripe.md) handles this automatically.
+Each line also keeps its own copy of the rate and label. If someone edits that tax rate next year, the order still says what the customer was actually charged.
 
-## Managing Taxes
+You never create tax lines yourself; they're written whenever the total is worked out.
+
+## When tax is worked out
+
+Tax is recalculated whenever the answer could have changed — an item added, an address entered, a delivery option chosen. Every one of those requests returns the updated cart, so a storefront never needs a separate "refresh the tax" call.
+
+**Step 1: Before an address is known**
+
+Prices are shown using the market's tax treatment. For an inclusive market the displayed price is the real one; for an added-on market tax simply hasn't been worked out yet.
+
+  **Step 2: Once the shipping address is entered**
+
+The address decides the real rate. Tax lines are written against each item, the delivery charge, and any taxable fee.
+
+  **Step 3: At completion**
+
+Whatever the tax is at that moment is what's charged, and the order keeps it. A rate change next month does not rewrite an order from last month.
+
+
+## Connecting a tax service
+
+Spree's built-in rate tables are fine when the rules are simple — one country, or a handful of clearly-defined rates. They become a liability where the rules are not: US sales tax varies by city and changes constantly, and cross-border EU VAT has thresholds that shift with your turnover.
+
+For those, connect a real tax service. **The provider is chosen per [Market](markets.md)**, which means one store can use its own rates in a simple market and an external service in a complicated one.
+
+```typescript Admin SDK
+const { data: providers } = await adminClient.taxProviders.list()
+```
 
-Tax categories and rates are managed in the Admin Panel under **Settings → Taxes**, or via the Admin API.
+A provider declares up front what it cannot do — no US local tax, no reverse charge — so the dashboard can warn a merchant who pairs it with a market that needs it, rather than quietly under-collecting.
 
-### Common Configurations
+Whichever provider is in use, the result is the same: tax lines on the order, in the same shape. Your storefront code doesn't change.
 
-**US store with state-level sales tax:**
-- Create zones for each taxable state
-- Create tax rates per zone (e.g., 8.25% for California, 6.25% for Texas)
-- Set `included_in_price: false`
+## Tax-exempt customers
 
-**EU store with VAT:**
-- Create a zone for EU countries
-- Create tax rates per country (e.g., 19% Germany, 20% France)
-- Set `included_in_price: true`
-- Set the EU zone as the default tax zone
+Business customers are often exempt, and the paperwork is real. Spree records a customer's or company's **tax identifier** — a VAT number, an ABN — and can validate it. Companies can also hold exemption certificates, scoped to the country or state that issued them.
 
-**Digital products in the EU:**
-- Create a "Digital" tax category
-- Add tax rates for each EU country using the customer's country VAT rate
-- Physical products use the seller's country VAT rate
+Exemption is decided when tax is worked out, not stored as a flag on the customer, so an expired certificate stops applying by itself. See [Companies & Catalogs](companies-and-catalogs.md).
 
-## Related Documentation
+## Related
 
-- [Markets](markets.md) — Tax-inclusive pricing per market
-- [Addresses](addresses.md) — Zones and address-based taxation
-- [Adjustments](taxes-discounts-fees.md) — Tax adjustments
-- [Orders](orders.md) — How taxes affect order totals
-- [Avalara integration](../../integrations/tax/avalara.md) — Automated tax calculation for complex jurisdictions
+- [Order totals](order-totals.md) — how tax rolls into what a customer pays
+- [Markets](markets.md) — where tax treatment and provider are chosen
+- [Addresses](addresses.md) — what determines the rate
+- [Companies & Catalogs](companies-and-catalogs.md) — B2B tax identifiers and exemptions

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