Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Plan how cross-border pricing works with tax-inclusive prices
Łukasz Adamczykb17f4a87cf80
diff --git a/CLAUDE.md b/CLAUDE.mdindex 1d25364453..58342ce327 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -24,7 +24,7 @@ Active plans (6.0 target, work pending):- `6.0-fulfillment-and-delivery.md` — Shipment→Fulfillment, ShippingMethod→DeliveryMethod, drop ShippingCategory, FulfillmentProvider strategy, pickup (merchant StockLocation) + pickup_point (third-party PickupPointProvider). **Shipped to 6-0-dev (Waves 2+4+6):** renames + deprecated twins, providers (Manual/Digital/Pickup/PickupPoint), dual-emit events, store pickup discovery endpoints, admin delivery_methods/delivery_zones CRUD + dashboard settings pages, FulfillmentMailer; Wave 7 shipping→delivery data migration remains- `6.0-returns-exchanges-claims.md` — First-class Return, Exchange, Claim models replacing ReturnAuthorization/Reimbursement chain. **COMPLETE (2026-08-05):** all three entities (+ permanent `ReturnLineItem`/`ExchangeLineItem`/`ClaimLineItem` line items), `Spree::HasStatus`, all fifteen workflows (each with a leading `validate` hook), `Refund#originator`, admin + store v3 APIs (transitions as PATCH member actions; no destroy — cancel instead), dashboard pages. Legacy chain **removed**: ReturnAuthorization/CustomerReturn/Reimbursement/ReimbursementType/legacy ReturnItem + eligibility validators + ReturnsCalculator classes all deleted, but their **tables deliberately survive to 6.1** as the data migration's source and rollback path. `spree:upgrade:migrate_returns` (`Spree::ReturnsMigrator`, defined in the rake file like its sibling upgrade tasks; anonymous-AR readers) is in the 5.6→6.0 manifest after the adjustments step; it needs no cursor because the preserved `number` is uniquely indexed on the new tables, so "what's left" is a `where.not(number: ...)` query and an interrupted run resumes for free. `ReturnAuthorizationReason`→`ReturnReason` (alias one release) + new `ClaimReason`; `Metafields` on all three. Capability replacements: `Spree::ReturnMailer#refunded_email` on `return.refunded` (replaces the reimbursement email), `Order#outstanding_balance` drops the reimbursement term (refunds already net out of `payment_total`), `Return#refunded_total` counts store credits too, `StoreCreditCategory.default_refund_category` (alias kept). **Reasons** ship admin-only CRUD (`/api/v3/admin/{return,claim,refund}_reasons`, `settings` scope) + a combined Settings → Reasons dashboard page + reason pickers on the create dialogs; `mutable` is never client-writable and the immutability guard lives on `Spree::NamedType` (`can_be_deleted?` + rename/destroy guards) because secret API keys authorize by scope and never consult CanCanCan. **No state machines (2026-08-02):** plain `status` string + inclusion validation; all fifteen transitions are workflows (`Returns::Receive`, `Exchanges::Fulfill`, `Claims::Resolve`, …) with `validate` hooks for return-eligibility policy and refunds as `external_step`. Nothing happens in a model or transition callback. Statuses live in a `class_attribute` via the core `Spree::HasStatus` concern (`has_status` + additive `add_status(value, after:)`, generating predicates and scopes) — extensible by design, additive only, and no transition graph (that would be a state machine again). **Return eligibility is a hook, not a policy engine (2026-08-03):** no window/restocking-fee/final-sale flag in core — a `validate` handler decides, enforcing for customers while letting staff override (it reads `created_by`), and region-varying policy reads `order.market`. Medusa/Saleor/Vendure ship no policy at all; Shopify's engine has no API. A `ReturnPolicy` model can arrive later behind the same hook.- `6.0-platform-auth.md` — Drop Devise, own auth stack, User→Customer/Staff rename (RefreshToken shipped in 5.4)-- `6.0-tax-provider.md` — Per-Market TaxProvider (market selects the provider, providers stateless/argless; global config class stays as fallback), replaces TaxRate.adjust + Calculator; reference provider: Avalara (decisions.md 2026-07-30). **Shipped to 6-0-dev (core-rewrite waves):** `Spree::TaxProvider::Base`/`Internal` as the sole TaxLine write path, called from `Carts::RecalculateTotals` behind the `money_frozen?` freeze. **Contract refined 2026-08-05 after the spree/spree#14056 review (decisions.md):** TaxLine gains `taxability_reason` + jurisdiction snapshot (e-invoice category/exemption codes derived at invoicing time, never stored); new `Spree::TaxIdentifier` model (customer/cart/order dual-FK, frozen order snapshot; validation via the kind-keyed `Spree.tax_id_validators` registry + async job on the geocoding precedent — NOT a provider method, and no registry client in core); exemptions = typed `estimate` input via `tax_resolve_exemptions_service` (boolean `exempt?` removed, no flags anywhere); explicit `tax_date:`; `refund(order, return_items, tax_date:)`; capability declarations (Internal declares no US local tax / no reverse charge / no one-stop-shop thresholds; `estimate` keeps its no-op return — a structured result + indeterminacy channel deferred as safely additive). **Phases 3-5 in development:** the enriched contract, `Spree::TaxIdentifier` + validator registry, exemption value objects, per-Market selection with commit/void/refund as external steps, and the Zone decoupling (rates carry `country_id`/`state_id`; `spree_tax_rates.zone_id` stays through 6.0 as the conversion source). **Phases 3-5 + the Zone decoupling shipped to `feature/v-3526` (PR #14410).** **Phase 7 is next and no longer gated (2026-08-07):** it pulls the minimal Company tree forward out of the B2B plan — Company → CompanyLocation → CompanyContact, `company_location_id` on both carts and orders, `company_id` as a fourth TaxIdentifier owner, `Spree::TaxExemptionCertificate` hanging off Company scoped by country/state, and the `ResolveExemptions` body; **no `tax_exempt` boolean anywhere** (supersedes the B2B plan's sketches), and Catalog/pricing/visibility stay 6.1. Pending after that: Phase 6 `spree_tax_avalara`, Phase 8 6.1 cleanup (drop `zone_id`, `null: false` on the tax `store_id`s, decide `Market#tax_inclusive`). Still open: delivery-rate tax display bypasses the provider+- `6.0-tax-provider.md` — Per-Market TaxProvider (market selects the provider, providers stateless/argless; global config class stays as fallback), replaces TaxRate.adjust + Calculator; reference provider: Avalara (decisions.md 2026-07-30). **Shipped to 6-0-dev (core-rewrite waves):** `Spree::TaxProvider::Base`/`Internal` as the sole TaxLine write path, called from `Carts::RecalculateTotals` behind the `money_frozen?` freeze. **Contract refined 2026-08-05 after the spree/spree#14056 review (decisions.md):** TaxLine gains `taxability_reason` + jurisdiction snapshot (e-invoice category/exemption codes derived at invoicing time, never stored); new `Spree::TaxIdentifier` model (customer/cart/order dual-FK, frozen order snapshot; validation via the kind-keyed `Spree.tax_id_validators` registry + async job on the geocoding precedent — NOT a provider method, and no registry client in core); exemptions = typed `estimate` input via `tax_resolve_exemptions_service` (boolean `exempt?` removed, no flags anywhere); explicit `tax_date:`; `refund(order, return_items, tax_date:)`; capability declarations (Internal declares no US local tax / no reverse charge / no one-stop-shop thresholds; `estimate` keeps its no-op return — a structured result + indeterminacy channel deferred as safely additive). **Phases 3-5 in development:** the enriched contract, `Spree::TaxIdentifier` + validator registry, exemption value objects, per-Market selection with commit/void/refund as external steps, and the Zone decoupling (rates carry `country_id`/`state_id`; `spree_tax_rates.zone_id` stays through 6.0 as the conversion source). **Phases 3-5 + the Zone decoupling shipped to `feature/v-3526` (PR #14410).** **Phase 7 is next and no longer gated (2026-08-07):** it pulls the minimal Company tree forward out of the B2B plan — Company → CompanyLocation → CompanyContact, `company_location_id` on both carts and orders, `company_id` as a fourth TaxIdentifier owner, `Spree::TaxExemptionCertificate` hanging off Company scoped by country/state, and the `ResolveExemptions` body; **no `tax_exempt` boolean anywhere** (supersedes the B2B plan's sketches), and Catalog/pricing/visibility stay 6.1. Pending after that: Phase 6 `spree_tax_avalara`, **Phase 8 cross-border pricing with tax-inclusive prices** (2026-08-11 live pass: `Pricing::Context.from_order` never carried the cart's market so market-scoped price lists were unreachable from a cart; `recalculate_for_address_change!` called the non-persisting `update_price`; restatement was applied even to prices set for the destination — the rule is now derive net-fixed unless the winning price list carries a `geographic?` rule, Shopify's model), Phase 9 6.1 cleanup (drop `zone_id`, `null: false` on the tax `store_id`s, decide `Market#tax_inclusive`). Still open: delivery-rate tax display bypasses the provider- `6.0-delivery-rate-provider.md` — Per-DeliveryMethod DeliveryRateProvider wrapping Stock::Estimator (calculators stay — 2026-07-27 reversal), `store_id` on ShippingMethod, enriched DeliveryRate (carrier/service/date/metadata); monorepo ships one reference multi-carrier provider (Shippo/EasyPost, pick pending — decisions.md 2026-07-29); method rows stay regional (no cross-market method entity)- `6.0-delivery-zones.md` — Zone → DeliveryZone with postal-code-range/prefix members (country-scoped); owns the full ~183-reference Zone consumer inventory; `Spree::Zone` dropped entirely by end of 6.0 (2026-07-27 — 6.0 is the breaking-change window)- `6.0-rich-text-descriptions.md` — Drop ActionText **entirely** at 6.0 (incl. CustomFields::RichText values + Order/User internal notes; gem dependency removed), store sanitized HTML in text columns, serve `field` + `field_html`, **write via `field_html`** (read/write symmetry). description_html serializer shipped 5.4; sanitizer shipped in **5.6.2** with a permissive-but-safe configurable allowlist + `sanitize_rich_text` step in the 5.5→5.6 upgrade manifest (decisions.md 2026-07-27/28), tightened to the Tiptap set at 6.0diff --git a/docs/plans/6.0-tax-provider.md b/docs/plans/6.0-tax-provider.mdindex e767cb0b0e..06d7ce8fbd 100644--- a/docs/plans/6.0-tax-provider.md+++ b/docs/plans/6.0-tax-provider.md@@ -1,6 +1,6 @@# Tax Provider Interface-**Status:** In progress — the provider seam, `Spree::TaxProvider::Internal` and the `TaxLine` write path shipped to 6-0-dev with the core-rewrite waves (see Current State). **Phases 3, 4 and 5 are in development** (contract enrichment, per-Market selection, commit/void/refund wiring, Zone decoupling). **Phase 7 (exemption certificates) is next up and no longer gated** — it builds the minimal Company tree itself (2026-08-07, see Key Decisions). Remaining after that: Phase 6 (the Avalara reference gem) and Phase 8 (the 6.1 cleanup of the schema 6.0 keeps deliberately).+**Status:** In progress — the provider seam, `Spree::TaxProvider::Internal` and the `TaxLine` write path shipped to 6-0-dev with the core-rewrite waves (see Current State). **Phases 3, 4 and 5 are in development** (contract enrichment, per-Market selection, commit/void/refund wiring, Zone decoupling). **Phase 7 (exemption certificates) is next up and no longer gated** — it builds the minimal Company tree itself (2026-08-07, see Key Decisions). Remaining after that: Phase 6 (the Avalara reference gem), Phase 8 (cross-border pricing with tax-inclusive prices — three defects found by the 2026-08-11 live pass) and Phase 9 (the 6.1 cleanup of the schema 6.0 keeps deliberately).> **Store binding (2026-07-29):** TaxRate and TaxCategory adopt the every-major-model-carries-a-store_id convention as part of this plan's implementation (`Spree::SingleStoreResource`, backfill task, NOT NULL in 6.1) — same treatment DeliveryMethod/StockLocation/DeliveryZone received on the 6.0 core-rewrite branch.@@ -13,7 +13,7 @@**Target:** Spree 6.0**Depends on:** Split Adjustments (6.0-6.1-split-adjustments.md — shipped; provides TaxLine). Phase 7 pulls the Company tree forward out of `6.1-channels-catalogs-b2b.md` rather than waiting on it — that plan keeps Catalog, per-company pricing and product visibility, and inherits the models this phase ships.**Author:** Damian + Claude-**Last updated:** 2026-08-07+**Last updated:** 2026-08-11## Summary@@ -404,6 +404,43 @@ Multiple certificates = multiple entries. Certificate *lifecycle* (verified/expi**Hook boundary:** the `set_tax_line_context` hook is NOT the exemption channel. Typed inputs — exemptions from `tax_resolve_exemptions_service`, the identifier from `#resolved_tax_identifier`, the tax date from the caller — arrive as named `estimate` parameters: declared shapes, one implementation each, no deep-merge collisions. The hook remains for untyped provider-specific extras only (riding into `TaxLine.data` / provider requests as the `context:` parameter); its doc comment — which currently names "exemption certificates, customer tax IDs" as its payload — must be corrected before the 6.0 hook-contract freeze.+### Cross-border pricing: derive net-fixed, unless the merchant priced that geography (2026-08-11)++A tax-inclusive price is expressed in *some* country's VAT. When the buyer is in another one, the+platform must decide whether the **shopper's price** stays put and the merchant's margin moves, or+the **merchant's net** stays put and the price moves. Both are coherent; the industry ships both and+names the first "price consistency".++Spree takes the two-tier answer, which is Shopify's:++1. **A price from a geo-scoped price list is final** — charged exactly as entered, never restated.+ `Spree::Price#final_for_destination?` is true when the winning list carries a rule that answers+ `geographic?` (`MarketRule`, `ZoneRule`). This is Shopify's carve-out: fixed per-country prices+ receive no adjustment.+2. **Everything else derives net-fixed** — the home rate out, the destination's on, via+ `VatPriceCalculation`. The merchant's take is preserved; the gross moves, cents and all.++**Why the carve-out keys on the rule and not on `price_list_id`.** A volume or customer-group list+price was set for a quantity or a group, not for a country — restating it protects the same margin a+base price's restatement protects. Only a rule that names a geography licenses the claim "this+figure is already correct for that geography."++**Why net-fixed is the default.** Four of the platforms surveyed derive this way by default+(WooCommerce, Magento/Adobe, Shopify, Vendure), and the alternative silently moves the merchant's+margin: with the German 19% price charged into France's 20%, the net falls 84.03 → 83.33 with nothing+on the order recording that the merchant absorbed it. Magento's own documentation states the+consequence of enabling consistency — "your profit margin changes by tax rate… The store absorbs any+difference between domestic and foreign VAT rates."++**Restatement is an Internal-provider capability, not a platform one.** `VatPriceCalculation` derives+both halves from `TaxRate` rows, so it can only work where those rows are the truth. An absent row is+ambiguous — *no tax due* or *computed by an engine* — and it reads as the former, which turns every+foreign destination on an external-provider market into an apparent zero-rated export. So+restatement runs for Internal and is skipped elsewhere, and a market on an external engine states its+destination prices through a geo-scoped price list instead. Shopify reached the same place from the+other direction: their dynamic tax-inclusive pricing reads a standard-rate table and is explicitly+incompatible with AvaTax.+### Provider is per-Market — selection, not constructionMarkets represent regional commerce operations; each market selects its tax engine. `Spree.default_tax_provider` stays as the **fallback** (market with no explicit provider, store without markets) — one config, returning a class, so a caller that only needs to name the default does not instantiate one.@@ -527,9 +564,9 @@ scope :for_address, ->(address) {}```-State-level rates override country-level (more specific wins). **Tax stops using Zone** — a data migration converts Zone records used by TaxRate into direct country/state FKs, and no code reads `zone_id` on TaxRate any more. The request-context readers went too (`Spree::Current.zone`/`default_tax_zone`, `Market#tax_zone`, `Purchase::Taxation#tax_zone`), replaced by `Spree::Current.tax_country`; `spree_tax_rates.zone_id` stays as the conversion source until Phase 8. Dropping the `Spree::Zone` model itself belongs to `6.0-delivery-zones.md`, which owns the full consumer inventory and does it inside 6.0.+State-level rates override country-level (more specific wins). **Tax stops using Zone** — a data migration converts Zone records used by TaxRate into direct country/state FKs, and no code reads `zone_id` on TaxRate any more. The request-context readers went too (`Spree::Current.zone`/`default_tax_zone`, `Market#tax_zone`, `Purchase::Taxation#tax_zone`), replaced by `Spree::Current.tax_country`; `spree_tax_rates.zone_id` stays as the conversion source until Phase 9. Dropping the `Spree::Zone` model itself belongs to `6.0-delivery-zones.md`, which owns the full consumer inventory and does it inside 6.0.-**`spree_tax_rates.zone_id` is dropped in 6.1, not 6.0.** The column is what `spree:migrate_tax_zones` converts *from*, and the manifest runs after `db:migrate` — so a migration dropping it in the same release would destroy the conversion's own input, and leave no rollback source if a merchant needs to re-run it. 6.0 therefore severs every reader (the `belongs_to :zone`, the zone scopes, and `Zone#has_many :tax_rates`, whose `dependent: :destroy` would otherwise delete live rates when a shipping zone is destroyed) and leaves the column in place, unread. This matches how `spree_adjustments` is handled by `migrate_adjustments_to_typed_rows`. **Phase 8** drops the column alongside the other converted-away schema.+**`spree_tax_rates.zone_id` is dropped in 6.1, not 6.0.** The column is what `spree:migrate_tax_zones` converts *from*, and the manifest runs after `db:migrate` — so a migration dropping it in the same release would destroy the conversion's own input, and leave no rollback source if a merchant needs to re-run it. 6.0 therefore severs every reader (the `belongs_to :zone`, the zone scopes, and `Zone#has_many :tax_rates`, whose `dependent: :destroy` would otherwise delete live rates when a shipping zone is destroyed) and leaves the column in place, unread. This matches how `spree_adjustments` is handled by `migrate_adjustments_to_typed_rows`. **Phase 9** drops the column alongside the other converted-away schema.## Design Details@@ -1081,7 +1118,7 @@ Tax-side only — shipping keeps Zone untouched; full Zone removal is deferred t```- Add `country_id`/`state_id` to `spree_tax_rates`; run the data task; sever every `zone_id` reader.- The column itself is dropped in **Phase 8**, not here — the conversion cannot drop its own input.+ The column itself is dropped in **Phase 9**, not here — the conversion cannot drop its own input.- Update the `/admin/tax_rates` serializer, permitted params and Ransack allowlist from `zone_id` to `country_id`/`state_id` — the only rework those endpoints take, and the reason they are worth building in Phase 3 rather than waiting.- Retire the tax-side zone readers rather than rewriting them: `Order#tax_zone`,`Spree::Current.zone`/`default_tax_zone`, `Market#tax_zone` and `Zone.default_tax` all answered@@ -1095,7 +1132,7 @@ Tax-side only — shipping keeps Zone untouched; full Zone removal is deferred tcall, not this one's — it stays out of the rule registry either way.- **Re-point whatever populates `DeliveryRate#tax_rate`.** The Estimator matches that rate through the Zone path this phase removes, so it must move to `for_address` to keep working. Mechanical only — preserving current behavior here does not require answering Open Question 1, though this is the natural moment to.- `spree_zones`/`spree_zone_members` are **not** dropped in 6.0, and neither is- `spree_tax_rates.zone_id` (Phase 8).+ `spree_tax_rates.zone_id` (Phase 9).### Phase 6: Avalara reference gem (`spree_tax_avalara`)@@ -1305,7 +1342,103 @@ account area is a 6.1 question, with the gated-channel work.**No dashboard work in this phase either.** The Company tree and certificates ship as API only;managing them in the admin UI belongs to the B2B release.-### Phase 8: 6.1 cleanup — the schema 6.0 deliberately kept+### Phase 8: cross-border pricing with tax-inclusive prices++**Ships in 6.0.** Three defects found by a live pass against a running server (2026-08-11), all in+the same seam: what a customer is charged when the destination's VAT rate differs from the home+zone's. None of them is visible in a single-country store, which is why the engine suites never+caught them — home zone equal to destination makes restatement a no-op.++**The rule this phase establishes, in two tiers** (Shopify's model — see Key Decisions):++1. **A price the merchant set for the buyer's geography is final.** Charged exactly as entered,+ never adjusted. Shopify: "add your prices at exactly the amount you want them to be charged.+ Adjustments aren't made to fixed prices per region."+2. **Otherwise derive, net-fixed.** Remove the home rate, apply the destination's — what+ `VatPriceCalculation` already does. The merchant's net is preserved and the gross moves.++#### The three defects++1. **Cart pricing reads the request, not the cart.** `Pricing::Context.from_order` copies+ `country: order.tax_country` but never the market, so `@market` falls back to+ `Spree::Current.market` — which is set only from the `x-spree-country` header or a `country`+ param, and otherwise defaults to the store's default market. Measured: a catalogue request with+ `x-spree-country: FR` correctly serves a French price list at 99.00, while a **cart on the French+ market** prices the same variant at 100.00 as soon as one request omits the hint — and the wrong+ figure persists. So the product page and the cart can only agree by coincidence, and a+ market-scoped price list is unreachable from a cart.++2. **The re-price on a destination change is computed and thrown away.** `Carts::Update#try_advance`+ correctly calls `cart.recalculate_for_address_change!` whenever `destination_changed?`+ (`ship_address_id`, `market_id`, `preferred_stock_location_id`), and that method's own comment+ says it "re-prices, re-taxes and rebuilds delivery proposals". It calls+ `line_items.reload.each(&:update_price)` — and `update_price` only **assigns**, where+ `recalculate_price` **persists** via `update_columns`. Measured through the Store API: shipping a+ US-home cart to Berlin leaves the line at 100.00 while the tax flips to German inclusive 15.97;+ a later quantity change (which routes through `recalculate_price`) writes the 119.00 the address+ change should have saved. The fulfillment appearing in the same response proves the method ran —+ only the price write was lost.++3. **Restatement is applied to prices that were already set for the destination.**+ `price_including_vat_for` calls `gross_amount` on whatever price row won, and `net_amount`+ divides by the **home** country's rate — there is nothing on a `Spree::Price` recording which+ country's VAT its figure includes. An explicit French price of 99.00 would therefore be treated+ as German-gross and restated to 99.83, destroying the price point the merchant chose.++Delivery is already correct here: rates are re-quoted from scratch on an address change, so a 20.00+flat rate becomes 22.43 for a 20% destination. This phase brings line items up to the behaviour+delivery already has.++#### Work++1. **`Pricing::Context.from_order` passes `market: order.market`.** Cart-stage pricing then depends+ on the cart, not on whether a client remembered a header. Audit the other constructors+ (`from_currency` has no owner to read a market from — it keeps the `Spree::Current` fallback,+ which is correct for a catalogue request).+2. **`Spree::PriceRule.geographic?`** — `false` on the base class, `true` on `MarketRule` and+ `ZoneRule`. Then `Spree::Price#final_for_destination?` is+ `price_list&.price_rules&.any?(&:geographic?)`, and both `price_including_vat_for` and+ `compare_at_price_including_vat_for` return the stored figure unchanged when it answers true.+ A volume or customer-group list price is still restated — it was priced for a quantity or a+ group, not for a country, so its margin needs the same protection as a base price.+3. **`recalculate_for_address_change!` calls `recalculate_price`.** One word, and the persisting+ method is already the one a quantity change uses.+4. **Restatement runs only where the rate table is the truth — i.e. the Internal provider.**+ `VatPriceCalculation` reads nothing but `TaxRate` rows, and an absent row is overloaded: it means+ *no tax is due here* (a zero-rated export — deduct the home VAT, charge net) or *tax is computed+ elsewhere* (an external engine — deduct nothing). It always assumes the first. Measured with the+ German home zone and a Japanese destination: **100.00 becomes 84.03**, the home VAT removed and+ nothing put back. That is exactly right for a real export, and exactly wrong for a market whose+ engine simply has no rows in this table — there, every foreign destination looks like a+ zero-rated export, so prices drop by the home VAT and tax reappears only at checkout, which is+ the wrong display convention for an EU buyer even when the total happens to land right.++ For Internal the table is complete by definition, so absence really does mean zero-rated and the+ current behaviour stands. Where the market's provider is not Internal, **skip restatement** — the+ rows it would read are not that market's tax. What a given provider gem chooses to say about the+ limitation is its own business. Shopify draws the same line: dynamic tax-inclusive pricing "uses+ only the standard tax rates for both the origin country and destination country" and is explicitly+ "not supported for stores on the Shopify Plus plan that use Avalara AvaTax."++ Such a market states its destination prices through a geo-scoped price list — the tier-1 rule. A+ read-only `rate_for` on the provider contract, letting an engine supply display rates, would+ dissolve the limitation; it stays with Open Question 1, which is the same question for delivery+ options.+5. **Specs for the cross-border matrix**, which nothing covers today: home == destination (no+ movement), home != destination (net-fixed movement, persisted), a geo-scoped list price (no+ movement), a non-geo list price (movement), a cart whose market differs from the request hint+ (the cart wins), a zero-rated export under Internal (net charged), and an external-provider+ market (no movement, capability declared).++#### What makes the re-pricing safe to disclose++A price moving under a customer mid-checkout is the real objection, not the cents.+`Carts::Complete#verify_expected_total` already fails with `cart_changed` and the current total when+the client's `expected_total` no longer matches, so a storefront gets an explicit "your total+changed" rather than a silent charge. That guard is what makes "re-price when the destination+changes" defensible; it must not be weakened.++### Phase 9: 6.1 cleanup — the schema 6.0 deliberately kept**Ships in 6.1, never inside 6.0.** Every item here needs a release boundary for one of tworeasons: a 6.0 install may not have run its data task yet, or a third party may still be passing@@ -1332,6 +1465,17 @@ manifest, so every install arriving at 6.1 has run them.## Constraints on Current Work+- **Cart-stage pricing reads the cart, never `Spree::Current`.** `Pricing::Context.from_order` must+ carry the owner's own `market` alongside its `country`. Anything that prices a cart line from the+ request context makes the same cart price differently between two requests — measured, and it+ persists. Catalogue requests keep the `Spree::Current` fallback; they have no owner to read.+- **A new `PriceRule` subclass must answer `geographic?`.** The default is `false`; a rule that+ narrows by geography returns `true` and thereby exempts its list's prices from VAT restatement.+ Getting this wrong on a new rule type silently changes what customers are charged abroad.+- **Re-pricing on a destination change must stay behind the drift guard.**+ `Carts::Complete#verify_expected_total` returning `cart_changed` is what makes a mid-checkout price+ movement disclosable rather than silent. Don't weaken it, and don't add re-pricing paths that skip+ it.- **No `tax_exempt` boolean anywhere.** Not on Company, not on CompanyLocation, not on Customer. Exemptionis a `Spree::TaxExemption` entry resolved from a certificate; a flag cannot name its jurisdiction or itslines. This supersedes the Company and CompanyLocation sketches in `6.1-channels-catalogs-b2b.md`.@@ -1359,6 +1503,11 @@ manifest, so every install arriving at 6.1 has run them.**Still open, and now sequenced after Phase 7** (2026-08-07 — it is one of the two remaining items on PR #14410). Phases 3–5 neither need nor are blocked by an answer, and the only knock-on is that a market pointed at an external provider shows no tax on its delivery options while checkout charges the provider's — a display defect, not a collection one, since the money still comes from the provider's TaxLines. Phase 5 re-pointed the rate matching mechanically. Dropping tax from the option labels entirely stays on the table as an outcome, not just a fallback; whichever way it lands, it should be settled with `6.0-delivery-rate-provider.md`, which owns `DeliveryRate` enrichment.Resolved (previously open):+- **Cross-border restatement scope (2026-08-11)** — derive net-fixed by default; never restate a+ price whose winning price list carries a `geographic?` rule. Settled with the two-tier decision in+ Key Decisions after surveying seven platforms; the alternative rules considered (any+ `price_list_id`, an explicit `prices_are_final` column) were rejected for letting a non-geographic+ list erode margin, and for adding a merchant-facing concept where a rule already states the intent.- **Context key discoverability** — no declaration mechanism. `estimate`'s `context:` is the hash produced by the `set_tax_line_context` hook: extensions register handlers, each returns a hash, and `run_hooks` deep-merges them all into one before the provider is called. Whatever rides it is either documented by the gem that reads it, or — if a merchant is meant to configure it — belongs on that provider's `Spree::Integration` as a preference, where it already gets persistence and an admin form. Handlers should namespace their contribution under the provider key (`{ 'avalara' => { … } }`), because unlike `TaxLine.data`, which one provider writes onto a row already stamped with `provider_id`, this hash is merged across every registered handler and same-key contributions overwrite each other in registration order. Declaring keys the way `unsupported_capabilities` is declared was considered and rejected: validating them would make the channel typed, and a typed input deserves a named `estimate` parameter rather than a hash — `context:` exists precisely for what does not warrant a contract. The residual cost is accepted: a mistyped key is silently ignored, which is a bug in an extension that owns both ends.- **Estimate return value** — `estimate` returns nothing meaningful; the rows it writes are the output, and a provider that cannot complete raises. The structured result and its indeterminacy channel are deferred, not rejected: both cases that motivated them are covered by capability declarations at configuration time, and a return value can be added later without breaking providers or callers.- **Caching for external providers** — left to the provider implementation; different providers have different caching needs.diff --git a/docs/plans/decisions.md b/docs/plans/decisions.mdindex 589becc8cc..26a14f3511 100644--- a/docs/plans/decisions.md+++ b/docs/plans/decisions.md@@ -1,3 +1,51 @@+## 2026-08-11: Cross-border tax-inclusive pricing derives net-fixed, except where the merchant priced that geography++A live pass against a running server found three defects in one seam — what a customer is charged+when the destination's VAT rate differs from the home zone's. `6.0-tax-provider.md` gains Phase 8 to+fix them (the 6.1 cleanup renumbers to Phase 9).++**The rule, which is Shopify's:** a price from a price list whose rules include a geographic one+(`MarketRule`, `ZoneRule`) is **final** — charged exactly as entered, never restated. Everything else+**derives net-fixed**: home rate out, destination rate on, via `VatPriceCalculation`. The merchant's+net is preserved and the gross moves.++**Why this matters beyond tax.** Two of the three defects are pricing defects, not tax defects:++1. `Pricing::Context.from_order` never carried the owner's `market`, so cart line pricing followed+ the request's `x-spree-country` hint (or the store default) instead of the cart's own market.+ Measured: a catalogue request with the hint served a French price list at 99.00 while the cart on+ that same French market priced at 100.00, and the wrong figure persisted. **Market-scoped price+ lists were therefore unreachable from a cart** — they work for the catalogue only.+2. `Cart#recalculate_for_address_change!` called `LineItem#update_price`, which assigns without+ saving, where `recalculate_price` persists. A destination change computed the restated price and+ discarded it; a later quantity change wrote it. So what a cross-border customer paid depended on+ the order of operations.++**Constraints this places on other work:** cart-stage pricing must read the cart's own market, never+`Spree::Current` (catalogue requests keep that fallback, having no owner); any new `PriceRule`+subclass must answer `geographic?`, since that predicate now decides whether its list's prices are+exempt from restatement; and re-pricing paths must stay behind+`Carts::Complete#verify_expected_total`, whose `cart_changed` failure is what makes a mid-checkout+price movement disclosable instead of silent.++**Restatement is a capability of the Internal provider, not of the platform.** `VatPriceCalculation`+derives both the home and destination rate from `TaxRate` rows, so it only works where those rows are+the whole truth. An absent row is ambiguous — *no tax is due here* or *tax is computed by an engine* —+and the code reads it as the former. Measured: German home zone, Japanese destination, no Japanese+rates, and 100.00 is charged as **84.03**. Correct for a genuine zero-rated export; wrong for a market+whose engine simply has no rows in that table, where it makes every foreign destination look like an+export. So restatement runs for Internal and is skipped elsewhere, with a geo-scoped price list as the+external-provider merchant's way to state destination prices. Shopify arrived at the same separation:+dynamic tax-inclusive pricing reads a standard-rate table and is explicitly unsupported alongside+AvaTax. A+read-only `rate_for` on the provider contract would dissolve the limitation and stays deferred with+the delivery-option quote question, which is the same problem for a different surface.++Surveyed for this: Shopify, WooCommerce, Magento/Adobe Commerce, BigCommerce, Saleor, Medusa,+Vendure, commercetools. Net-fixed is the majority default (WooCommerce, Magento, Shopify, Vendure);+the headless platforms (Saleor, commercetools, Medusa) refuse to derive at all and require a price+per channel/region.+## 2026-08-09: Metadata consolidated to one column — `public_metadata` dropped, `private_metadata` renamedImplements the 2026-03-16 consolidation decision. All thirty metadata-carrying