Skip to content

armgit / spree

Public Imported from GitHub
0

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.

Plan how cross-border pricing works with tax-inclusive prices

Łukasz Adamczykb17f4a87cf80
diff --git a/CLAUDE.md b/CLAUDE.md
index 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.0
diff --git a/docs/plans/6.0-tax-provider.md b/docs/plans/6.0-tax-provider.md
index 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 construction
Markets 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 t
call, 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 two
reasons: 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. Exemption
is a `Spree::TaxExemption` entry resolved from a certificate; a flag cannot name its jurisdiction or its
lines. 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.md
index 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` renamed
Implements the 2026-03-16 consolidation decision. All thirty metadata-carrying