@spree/docs 0.1.182 → 0.1.183

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

@@ -3,8 +3,6 @@ title: Pricing
 description: Prices, Price Lists, Price Rules, and the Pricing Context — Spree's flexible pricing engine for regional, wholesale, volume, and market-based pricing.
 ---
 
-import { Since } from '/snippets/since.mdx';
-
 ## Overview
 
 Spree's pricing system supports both simple single-currency pricing and advanced multi-currency, rule-based pricing through Price Lists. Every [Variant](products.md#variants) can have multiple prices — a base price per currency, plus additional prices from Price Lists that apply conditionally based on rules like geography, customer segment, or quantity.
@@ -94,7 +92,7 @@ spree api post /prices/bulk_upsert -d '{
 ```
 
 
-## Price Lists  
+## Price Lists
 
 Price Lists allow you to create different pricing strategies based on various conditions. This enables advanced pricing scenarios like:
 
@@ -165,27 +163,27 @@ spree api patch /price_lists/pl_xxx/activate
 ```
 
 
-## Price Rules 
+## Price Rules
 
 Price Rules define conditions that must be met for a Price List to apply. Spree includes five built-in rule types:
 
 | Rule | Description | Use Case |
 |------|-------------|----------|
 | **Market Rule** | Matches based on the current [Market](markets.md) | Regional pricing across markets |
-| **Zone Rule** | Matches based on the customer's geographic zone | Country or state-level pricing |
+| **Channel Rule** | Matches based on the [Channel](channels.md) the customer is buying through | App-only or in-store pricing |
 | **User Rule** | Matches specific customer accounts | VIP customers, wholesale accounts |
 | **Customer Group Rule** | Matches members of customer groups | Loyalty tiers, membership pricing |
 | **Volume Rule** | Matches based on quantity purchased | Bulk discounts, tiered pricing |
 
-### Market Rule 
+### Market Rule
 
-The recommended approach for regional pricing when using Markets. Applies the Price List when the customer is in one of the specified markets.
+Regional pricing. Applies the Price List when the customer is in one of the specified markets.
 
 **Example:** Price a product at $29.99 in North America and €24.99 in Europe, rather than relying on exchange rate conversion.
 
-### Zone Rule
+### Channel Rule
 
-Applies based on the customer's geographic zone. Useful for regional or country-specific pricing when not using Markets.
+Applies when the customer is buying through a particular sales channel — a discount that exists only in the mobile app, or a price that only applies at a retail till.
 
 ### User Rule
 
@@ -207,7 +205,7 @@ Applies based on quantity purchased. Supports `min_quantity` and `max_quantity`
 
 > **INFO:** Custom Price Rules can be created for specialized pricing logic. See the [Customization Quickstart](../customization/quickstart.md) for details.
 
-## Pricing Context 
+## Pricing Context
 
 When resolving prices, Spree considers the full context of the request:
 
@@ -215,8 +213,8 @@ When resolving prices, Spree considers the full context of the request:
 |---------|--------|-------------|
 | Currency | Market or request header | The currency to price in |
 | Market | Customer's country | The [Market](markets.md) for market-based rules |
-| Zone | Customer's address | The geographic zone for zone-based rules |
-| Customer | JWT authentication | The logged-in customer for user-based rules |
+| Channel | The API credential in use | The [Channel](channels.md) for channel-based rules |
+| Customer | Authentication | The signed-in customer for user-based rules |
 | Quantity | Cart line item | The quantity for volume-based rules |
 | Date | Current time | For time-based Price List scheduling |
 
@@ -236,7 +234,7 @@ Price Lists are managed in the Admin Panel under **Products → Price Lists**, o
 
 Each Price List contains prices for specific variants and currencies. Products can be added to a Price List, and individual variant prices set within it.
 
-## Price History (EU Omnibus Directive) 
+## Price History (EU Omnibus Directive)
 
 Spree automatically records price changes for EU Omnibus Directive compliance. When a product goes on sale, EU regulations require displaying the lowest price in the preceding 30 days alongside the discounted price.
 

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

@@ -3,8 +3,6 @@ title: Products
 description: How Spree models products, variants, option types, images, prices, and categories — the building blocks of every catalog and storefront.
 ---
 
-import { Since } from '/snippets/since.mdx';
-
 ## Overview
 
 A product represents something you sell. Each product has one or more **variants** — the actual purchasable items with their own SKU, price, and inventory. For example, a "T-Shirt" product might have variants for each size and color combination.
@@ -16,15 +14,16 @@ Products are organized into **categories** — a flexible hierarchy for grouping
 ```mermaid
 erDiagram
     Product ||--o{ Variant : "has many"
-    Product }o--o{ OptionType : "has many"
-    Product ||--o{ Classification : "has many"
-    Variant ||--o{ Price : "has many"
-    Variant ||--o{ StockItem : "has many"
-    Variant ||--o{ Image : "has many"
-    Variant }o--o{ OptionValue : "has many"
+    Product }o--o{ OptionType : "varies by"
+    Product }o--o{ Category : "filed under"
+    Product }o--o{ Collection : "grouped into"
+    Product ||--o{ Media : "images and video"
+    Product }o--|| DeliveryProfile : "ships by"
+    Variant ||--o{ Price : "one per currency"
+    Variant ||--o{ StockLevel : "stocked per location"
+    Variant }o--o{ OptionValue : "identified by"
     OptionType ||--o{ OptionValue : "has many"
-    Taxon ||--o{ Classification : "has many"
-    Taxonomy ||--o{ Taxon : "has many"
+    Category ||--o{ Category : "nests under"
 
     Product {
         string name
@@ -36,7 +35,7 @@ erDiagram
 
     Variant {
         string sku
-        boolean is_master
+        string barcode
         decimal weight
     }
 
@@ -221,7 +220,7 @@ spree api delete /products/prod_xxx
 
 > **TIP:** Operating on many products at once? The Admin API has bulk actions — `bulkStatusUpdate`, `bulkAddToCategories`, `bulkAddTags`, `bulkDestroy`, and more. See the [Admin API endpoint index](../../api-reference/admin-api/endpoints.md).
 
-## Seller submissions 
+## Seller submissions
 
 On a marketplace, a seller lists a product but does not publish one. They submit it, and the marketplace decides. This adds two statuses to the three above — both hidden from the storefront, since only `active` is visible.
 
@@ -606,14 +605,19 @@ See the [Pricing](pricing.md) guide for details on Price Lists, Price Rules, and
 
 ## Categories
 
-Categories provide a flexible way to organize products into hierarchical trees. Internally, Spree uses Taxonomies (category trees) and Taxons (nodes within those trees), but the Store API exposes them simply as **Categories**.
+There are two ways to group products, and they answer different questions.
+
+**Categories** are a hierarchy — the navigation tree a shopper browses. Clothing contains T-Shirts, which contains Long Sleeve. A product can sit in several categories, and each one has a permalink built from its path.
+
+**Collections** are flat groupings — "Summer 2025", "Best Sellers", "Under $50". A collection can be curated by hand, or defined by rules so products join and leave it on their own as their price, tags or stock change.
 
-For example:
-- **Categories** → Clothing → T-Shirts, Dresses
-- **Brands** → Nike, Adidas, Puma
-- **Collections** → Summer 2025, Best Sellers
+| | Categories | Collections |
+|---|---|---|
+| Shape | Nested tree | Flat list |
+| Membership | You assign it | Assigned, or matched by rules |
+| Typical use | Site navigation | Merchandising and campaigns |
 
-Products can belong to multiple categories.
+A brand is usually best modelled as one or the other rather than as a separate concept — a category if you want it in the navigation tree, a collection if it's a landing page.
 
 
 ```typescript Store SDK
@@ -650,7 +654,19 @@ curl 'https://api.mystore.com/api/v3/store/categories/clothing/shirts/products?l
 
 > **INFO:** Category `name` and `description` fields are translatable.
 
-## Publications and Sales Channels 
+Collections work the same way from a storefront's point of view:
+
+```typescript Store SDK
+const { data: collections } = await client.collections.list()
+
+const { data: products } = await client.collections.products.list('summer-2025', {
+  limit: 12,
+})
+```
+
+A rule-based collection is defined once and maintains itself — set it to match everything tagged `sale` and under $50, and products appear and disappear as those facts change. Ordering can be manual or by a rule such as newest first.
+
+## Publications and Sales Channels
 
 A product is visible on a [Channel](channels.md) only when a `ProductPublication` record joins the two. Publications carry an optional time window so a product can be scheduled to go live and come down without code or manual toggles.
 

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

@@ -5,7 +5,9 @@ description: Build percentage and fixed-amount discounts, free shipping, BOGO of
 
 ## Overview
 
-Promotions give money off an order — a percentage off, free shipping, or free items added to the cart. A promotion is a campaign definition: **rules** decide when it applies, **actions** decide what it does. When a promotion applies, its actions write [Discount](taxes-discounts-fees.md#discounts) rows on the order.
+A promotion is a campaign: a percentage off, free shipping, or free items in the cart. **Rules** decide when it applies, **actions** decide what it does.
+
+A promotion is a *rule that exists on its own*, set up in advance and lasting across many orders. What lands on any one order is a [Discount](discounts.md) — the record of money actually coming off. The promotion is the campaign; the discount is what a particular customer got.
 
 ```mermaid
 erDiagram
@@ -52,14 +54,13 @@ Promotions can be activated in two ways:
 - **Automatic promotions** — applied on their own when the rules are met (e.g. free shipping on orders over $50)
 - **Coupon code promotions** — applied when a customer enters a valid code during checkout
 
-### How discounts are recorded
+### When promotions compete
 
-Each applied promotion becomes one or more Discount rows on the order — on a specific line item or on a fulfillment, never a loose adjustment. Each row keeps a copy of the coupon code and the configured value ("10% off"), so the order still tells the whole story even if the promotion is deleted later.
+Several promotions can qualify for the same item at once. Spree applies **only the one that saves the customer the most**, and records just that one.
 
-Two things follow from this design:
+Losing candidates aren't stored or tracked — they're simply reconsidered on every cart change. So a promotion that loses today can win tomorrow, when the basket changes, without any bookkeeping to keep straight.
 
-- **Only winners are stored.** When several promotions compete for the same item, Spree picks the one that saves the customer the most and writes only that one. Losing candidates are recomputed on every cart change, so a promotion that loses today can win tomorrow without any bookkeeping.
-- **A discount on the whole order is shared out across the items.** If a customer later returns one item, Spree knows exactly how much of the discount belonged to it.
+What an applied promotion leaves behind on the order is a [Discount](discounts.md) — a permanent record that survives the promotion being edited or deleted.
 
 ## Promotion Attributes
 
@@ -112,7 +113,7 @@ You can also [build your own rules](../how-to/custom-promotion.md) for business-
 
 Actions define what happens when a promotion applies.
 
-### CreateAdjustment
+### Order discount (`CreateAdjustment`)
 
 A discount on the whole order. The amount is distributed proportionally across the line items — there is no single order-level row, so per-item reporting and partial returns always know their share.
 
@@ -120,7 +121,7 @@ A discount on the whole order. The amount is distributed proportionally across t
 
 **Use case:** "10% off your order", "$20 off orders over $100".
 
-### CreateItemAdjustments
+### Item discount (`CreateItemAdjustments`)
 
 A discount on individual line items. Only items that match the promotion's rules receive it — if a Category rule says "Electronics", only electronics are discounted.
 
@@ -128,13 +129,13 @@ A discount on individual line items. Only items that match the promotion's rules
 
 **Use case:** "15% off shoes", "Buy 2+ shirts get 10% off each".
 
-### FreeShipping
+### Free shipping (`FreeShipping`)
 
 Writes a discount on each fulfillment covering its delivery cost. The row is kept even when the cost is zero — its presence is what marks the order as having free shipping.
 
 **Use case:** "Free shipping on orders over $75", "Free shipping with code FREESHIP".
 
-### CreateLineItems
+### Free items (`CreateLineItems`)
 
 Adds specified products to the cart when the promotion is eligible, checking stock first. Items are not removed automatically if eligibility is lost — customers remove them manually.
 
@@ -245,7 +246,7 @@ Automatic promotions need no customer action at all — they are evaluated on ev
 
 ## Related Documentation
 
-- [Taxes, Discounts & Fees](taxes-discounts-fees.md) — the Discount rows promotions write, and manual discounts
+- [Discounts](discounts.md) — the rows promotions write, and manual discounts
 - [Build Custom Promotion Rules & Actions](../how-to/custom-promotion.md) — step-by-step guide to custom rules, actions and adjusters
 - [Calculators](calculators.md) — promotion calculators
 - [Carts](carts.md) — the cart lifecycle promotions act on

package/dist/developer/core-concepts/search-filtering.md

@@ -3,13 +3,11 @@ title: Search & Filtering
 description: "Use Ransack-style query parameters to search, filter, sort, and paginate products, taxons, and other resources through the Spree Store API."
 ---
 
-import { Since } from '/snippets/since.mdx';
-
 ## Overview
 
 Spree provides powerful search, filtering, and sorting capabilities for products and other resources. The Store API supports:
 
-- Full-text search across product names, SKUs, and searchable product metafields
+- Full-text search across product names, SKUs, and searchable custom fields
 - Attribute-based filtering (price range, availability, stock status)
 - Category and taxon filtering
 - Faceted search with filter counts
@@ -276,7 +274,7 @@ curl 'https://api.mystore.com/api/v3/store/products?page=1&limit=24' \
 
 See [Querying](../../api-reference/store-api/querying.md) for the full list of filtering, sorting, and pagination options.
 
-## Search Providers 
+## Search Providers
 
 Spree uses a pluggable search provider architecture. The default provider uses SQL (ILIKE + Ransack). For production catalogs with 1,000+ products, we recommend switching to [Meilisearch](../../integrations/search/meilisearch.md) for typo tolerance, relevance ranking, and faster faceted search.
 

package/dist/developer/core-concepts/store-credits-gift-cards.md

@@ -3,9 +3,6 @@ title: Store Credits & Gift Cards
 description: How Spree models store credits and gift cards — stored value balances, redeemable codes, and checkout usage for refunds, loyalty, and gifting.
 ---
 
-import { Since } from '/snippets/since.mdx';
-
-
 ## Overview
 
 Spree provides two stored value mechanisms that customers can use at checkout:

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