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.

Stop deriving invoice codes in core

Łukasz Adamczyka19d07e2fa72
diff --git a/docs/plans/6.0-tax-provider.md b/docs/plans/6.0-tax-provider.md
index bf8d4d3e66..abd5d3c1e0 100644
--- a/docs/plans/6.0-tax-provider.md
+++ b/docs/plans/6.0-tax-provider.md
@@ -179,9 +179,19 @@ Why this is needed: European e-invoices must state, for **every** line, which ta
**Deliberately NOT columns:** the invoice category code, the exemption reason code and the legal-reference wording. All three follow deterministically at invoicing time from `taxability_reason` plus order facts — the pattern Odoo uses, and Odoo's whole job is producing these invoices: it derives the codes at export from tax configuration and the sale's facts, and stores none of them per line. No surveyed commerce platform (Medusa, Saleor, commercetools, Shopify) stores them either. Storing the reason instead of the legal codes keeps core out of a legal vocabulary that gets revised on someone else's schedule, while still giving e-invoicing integrations everything they need. One-sentence rationale for the field: *a machine-readable reason distinguishes zero-tax causes that land in different boxes of a tax return, and lets e-invoicing integrations derive the category and exemption codes that European invoicing mandates require.*
-**Core ships the lookup maps** as code, not data — updatable with a release: reason → invoice category code, and reason → exemption reason code for the cross-border cases, plus a `TaxLine#category_code` helper. Both target code lists are the ones European e-invoices use (identified in **Regulatory background**).
-
-| `taxability_reason` | Invoice category code | Exemption reason code |
+**Core ships no code maps.** Deriving the invoice category code and the exemption reason code is
+the e-invoicing integration's job, because those code lists belong to a regime rather than to
+commerce: VATEX is maintained by the European Commission and revised roughly twice a year, and
+the EN 16931 category subset carries EU-only members (`K` for intra-EU supply, `L`/`M` for the
+Spanish territories). A merchant invoicing under India's GST, Brazil's NF-e or Saudi ZATCA needs a
+different mapping entirely, and a core map named as though it were universal would quietly hand
+them European codes.
+
+What core guarantees instead is that `taxability_reason` distinguishes every case a mapping needs
+to tell apart — which is the property that makes an external mapping possible at all. The
+correspondence for European invoicing, for reference rather than as shipped code:
+
+| `taxability_reason` | EN 16931 category code | VATEX exemption reason code |
|---|---|---|
| `standard_rated`, `reduced_rated` | S | — |
| `zero_rated` | Z | — |
@@ -192,7 +202,8 @@ Why this is needed: European e-invoices must state, for **every** line, which ta
| `not_subject_to_tax` | O | VATEX-EU-O |
| `not_collecting` | nil — no meaningful code (not registered in the jurisdiction; no EU VAT invoice to produce) | — |
-The map is not exhaustive of either code list — a treatment core doesn't model needs an extension to register the reason together with its code mapping. The one gap worth naming: for a genuinely exempt supply (healthcare, education, financial services) the exemption reason code cannot come from this map at all, because it depends on *which* exemption applied. That code stays with the exemption input and the tax-category configuration.
+A treatment core does not model needs an extension to register the reason, and that extension owns
+the mapping for it too.
Both fields are written by every provider, and both are covered by the write contract above — including on zero-amount rows, which is where the reason does its real work.
@@ -970,7 +981,7 @@ The **admin** side adds `validation_status`, `validated_at`, `validation_evidenc
**Tax lines.** The store serializer already exists (`label`, `rate`, `included`, `amount`) but no store endpoint consumes it — only `/admin/orders/:id/tax_lines`. Two changes:
- **Expose tax lines on the Store API**, nested on cart and order line items. Totals alone cannot render an order confirmation or an account invoice, and every comparable platform exposes per-line tax to the customer (Medusa, commercetools, Vendure, Shopify's Customer Account API).
-- **`taxability_reason` and the jurisdiction snapshot are admin-only.** No surveyed platform exposes a machine-readable reason to buyers, and the customer-facing need is met by `label`, which is already there. The cost of this choice is asymmetric in our favour: withholding a field and adding it later is additive, exposing one and removing it is breaking. The admin serializer gains `taxability_reason`, `country_iso`, `state_code`, `category_code`, **and `data`** — currently unserialized anywhere, though it is exactly the jurisdiction breakdown an e-invoicing integration needs.
+- **`taxability_reason` and the jurisdiction snapshot are admin-only.** No surveyed platform exposes a machine-readable reason to buyers, and the customer-facing need is met by `label`, which is already there. The cost of this choice is asymmetric in our favour: withholding a field and adding it later is additive, exposing one and removing it is breaking. The admin serializer gains `taxability_reason`, `country_iso`, `state_code` **and `data`** — currently unserialized anywhere, though it is exactly the jurisdiction breakdown an e-invoicing integration needs. No derived invoice code is exposed: that mapping belongs to the integration, not to core.
- **Ransack allowlist** on `Spree::TaxLine` for `taxability_reason`, `country_iso` and `state_code`. Reporting is the stated rationale for those columns — "which country's tax was this, and which sales were reverse-charged" has to be answerable — and without the allowlist they are write-only.
**Tax rates.** `/admin/tax_rates` — full CRUD, admin-only (rates are back-office configuration; the storefront never sees them). This plan owns building them even though `6.0-admin-api.md` carries the checkboxes, for a blunt reason: **TaxRate rows are the Internal provider's entire configuration**, so without these endpoints the default tax engine cannot be set up or inspected through the API at all, and nothing about its behavior can be verified outside a console or a spec. Tax categories already have their endpoints; rates are the missing half.
@@ -1006,7 +1017,7 @@ Shipped with the core-rewrite waves, not as originally phased: no "Internal dele
- TaxLine: `taxability_reason` + vocabulary registry + the invoice-category / exemption-reason lookup maps + `country_iso`/`state_code` columns; zero-amount write contract in the Internal provider.
- `Spree::TaxIdentifier` model + customer/cart/order FKs + `readonly?` freeze + completion copy step.
-- API: `/admin/tax_rates` CRUD (without it the Internal provider cannot be configured or verified through the API — see the API surface section), tax identifier endpoints (with admin `validatable` + the re-validate action), tax lines exposed on the Store API, admin tax-line serializer gaining `taxability_reason`/jurisdiction/`category_code`/`data`, and the Ransack allowlist for tax reporting.
+- API: `/admin/tax_rates` CRUD (without it the Internal provider cannot be configured or verified through the API — see the API surface section), tax identifier endpoints (with admin `validatable` + the re-validate action), tax lines exposed on the Store API, admin tax-line serializer gaining `taxability_reason`/jurisdiction/`data`, and the Ransack allowlist for tax reporting.
- `estimate` signature: `tax_date:`/`tax_identifier:`/`exemptions:`/`context:`; `refund(order, return_items, tax_date:)` replaces `refund(owner, amount)`; `exempt?` removed.
- `Spree::TaxExemption` + `ItemOverride` value objects; `tax_resolve_exemptions_service` dependency (default empty); `#resolved_tax_identifier` on `Spree::Purchase::Taxation`.
- `Spree::TaxIdValidator::Base` + `Spree.tax_id_validators` registry (empty by default, class names) + `Spree::TaxIdentifiers::Validate` (sole writer of the validation columns) + `ValidateJob` + `Spree.queues.tax_identifiers` + the `after_commit` enqueue guarded on kind/value changes.
diff --git a/packages/admin-sdk/src/types/generated/TaxLine.ts b/packages/admin-sdk/src/types/generated/TaxLine.ts
index e0b7f1e082..38311212c9 100644
--- a/packages/admin-sdk/src/types/generated/TaxLine.ts
+++ b/packages/admin-sdk/src/types/generated/TaxLine.ts
@@ -1,4 +1,4 @@
-// Typelizer digest 0e64b9d1f2d893adfe64ad0ba9a12ad8
+// Typelizer digest 72bdc039886bf786c6204b06fca47bf3
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
@@ -21,7 +21,6 @@ interface TaxLine {
data: Record<string, unknown> | null;
created_at: string;
updated_at: string;
- category_code: string | null;
}
export default TaxLine;
diff --git a/spree/api/app/serializers/spree/api/v3/admin/tax_line_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/tax_line_serializer.rb
index 451f13a807..92e329fafa 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/tax_line_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/tax_line_serializer.rb
@@ -6,8 +6,7 @@ module Spree
typelize amount: [:string, nullable: false], display_amount: [:string, nullable: false],
provider_id: [:string, nullable: true], metadata: ['Record<string, unknown>', nullable: true],
taxability_reason: [:string, nullable: true], country_iso: [:string, nullable: true],
- state_code: [:string, nullable: true], category_code: [:string, nullable: true],
- data: ['Record<string, unknown>', nullable: true]
+ state_code: [:string, nullable: true], data: ['Record<string, unknown>', nullable: true]
# The treatment and its jurisdiction stay admin-only: no surveyed
# platform shows a buyer a machine-readable tax reason, and `label`
@@ -15,12 +14,6 @@ module Spree
# breakdown, which is what an e-invoicing integration reads.
attributes :provider_id, :metadata, :taxability_reason, :country_iso, :state_code, :data,
created_at: :iso8601, updated_at: :iso8601
-
- # Derived from the reason at read time, never stored — the code lists
- # are revised on someone else's schedule.
- attribute :category_code do |tax_line|
- tax_line.category_code
- end
end
end
end
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/orders/tax_lines_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/orders/tax_lines_controller_spec.rb
index 4732e37484..a766265101 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/orders/tax_lines_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/orders/tax_lines_controller_spec.rb
@@ -32,7 +32,6 @@ RSpec.describe Spree::Api::V3::Admin::Orders::TaxLinesController, type: :control
row = json_response['data'].first
expect(row['taxability_reason']).to eq('standard_rated')
- expect(row['category_code']).to eq('S')
expect(row['country_iso']).to eq('DE')
expect(row['state_code']).to be_nil
expect(row['data']['jurisdictions'].first['name']).to eq('DE')
diff --git a/spree/core/app/models/spree/tax_line.rb b/spree/core/app/models/spree/tax_line.rb
index 119432e4fb..82faf314b1 100644
--- a/spree/core/app/models/spree/tax_line.rb
+++ b/spree/core/app/models/spree/tax_line.rb
@@ -9,43 +9,19 @@ module Spree
has_prefix_id :tl
- # Why this line was taxed the way it was. Configuration, not a frozen
- # constant — a provider modelling a treatment core doesn't know about
- # registers its reason here, together with an INVOICE_CATEGORY_CODES entry.
- # The bar for a new value: it maps to a distinct invoice category code, or
- # to a distinct box on a tax return.
+ # Why this line was taxed the way it was — the machine-readable cause, kept
+ # free of any one jurisdiction's invoice vocabulary so reporting and
+ # e-invoicing can map it to whatever codes their regime requires.
+ #
+ # Configuration, not a frozen constant — a provider modelling a treatment
+ # core doesn't know about registers its reason here. The bar for a new
+ # value: it distinguishes a treatment that reporting or invoicing has to
+ # tell apart, not merely a different amount.
class_attribute :taxability_reasons,
default: %w[standard_rated reduced_rated zero_rated reverse_charge
intra_community_supply export customer_exempt product_exempt
not_collecting not_subject_to_tax]
- # Reason -> EN 16931 invoice category code (BT-151), from the UNTDID 5305
- # list. Shipped as code so a revision rides a release rather than a data
- # migration. Not exhaustive of the code list: `not_collecting` has no
- # meaningful code, since there is no EU VAT invoice to produce.
- INVOICE_CATEGORY_CODES = {
- 'standard_rated' => 'S',
- 'reduced_rated' => 'S',
- 'zero_rated' => 'Z',
- 'reverse_charge' => 'AE',
- 'intra_community_supply' => 'K',
- 'export' => 'G',
- 'customer_exempt' => 'E',
- 'product_exempt' => 'E',
- 'not_subject_to_tax' => 'O'
- }.freeze
-
- # Reason -> EN 16931 exemption reason code (BT-121) for the cross-border
- # cases. Genuinely exempt supplies (healthcare, education, financial
- # services) are absent by design: their code depends on which exemption
- # applied, which lives with the exemption input and the tax category.
- EXEMPTION_REASON_CODES = {
- 'reverse_charge' => 'VATEX-EU-AE',
- 'intra_community_supply' => 'VATEX-EU-IC',
- 'export' => 'VATEX-EU-G',
- 'not_subject_to_tax' => 'VATEX-EU-O'
- }.freeze
-
# Provider payloads (jurisdiction breakdowns, external ids) read nil-safe.
attribute :data, default: -> { {} }
@@ -83,22 +59,6 @@ module Spree
line_item || fulfillment || fee
end
- # The EN 16931 invoice category code (BT-151) an e-invoice line carries.
- #
- # @return [String, nil] nil when the reason is unset or maps to no code
- def category_code
- INVOICE_CATEGORY_CODES[taxability_reason]
- end
-
- # The EN 16931 exemption reason code (BT-121). Nil for a genuinely exempt
- # supply, whose code depends on which exemption applied rather than on the
- # reason alone.
- #
- # @return [String, nil]
- def exemption_reason_code
- EXEMPTION_REASON_CODES[taxability_reason]
- end
-
def included?
included
end
diff --git a/spree/core/spec/models/spree/tax_line_spec.rb b/spree/core/spec/models/spree/tax_line_spec.rb
index 9a087721e8..dd86bf1ca8 100644
--- a/spree/core/spec/models/spree/tax_line_spec.rb
+++ b/spree/core/spec/models/spree/tax_line_spec.rb
@@ -67,37 +67,6 @@ describe Spree::TaxLine, type: :model do
end
end
- describe 'invoice codes' do
- subject(:tax_line) { described_class.new }
-
- it 'maps rated reasons to a category code without an exemption reason' do
- tax_line.taxability_reason = 'reduced_rated'
- expect(tax_line.category_code).to eq('S')
- expect(tax_line.exemption_reason_code).to be_nil
- end
-
- it 'maps cross-border reasons to both codes' do
- tax_line.taxability_reason = 'intra_community_supply'
- expect(tax_line.category_code).to eq('K')
- expect(tax_line.exemption_reason_code).to eq('VATEX-EU-IC')
- end
-
- it 'leaves an exempt supply without an exemption reason code' do
- tax_line.taxability_reason = 'product_exempt'
- expect(tax_line.category_code).to eq('E')
- expect(tax_line.exemption_reason_code).to be_nil
- end
-
- it 'has no code for a jurisdiction the merchant does not collect in' do
- tax_line.taxability_reason = 'not_collecting'
- expect(tax_line.category_code).to be_nil
- end
-
- it 'has no code without a reason' do
- expect(tax_line.category_code).to be_nil
- end
- end
-
describe 'provider data' do
it 'defaults to an empty hash so payloads read nil-safe' do
expect(described_class.new.data).to eq({})
diff --git a/spree/core/spec/models/spree/tax_provider/internal_spec.rb b/spree/core/spec/models/spree/tax_provider/internal_spec.rb
index e12dd10dd1..3342235592 100644
--- a/spree/core/spec/models/spree/tax_provider/internal_spec.rb
+++ b/spree/core/spec/models/spree/tax_provider/internal_spec.rb
@@ -29,7 +29,6 @@ describe Spree::TaxProvider::Internal, type: :model do
tax_line = order.tax_lines.reload.sole
expect(tax_line.taxability_reason).to eq('standard_rated')
- expect(tax_line.category_code).to eq('S')
expect(tax_line.country_iso).to eq(order.tax_address.country.iso)
expect(tax_line.state_code).to eq(order.tax_address.state&.abbr)
end
@@ -88,7 +87,6 @@ describe Spree::TaxProvider::Internal, type: :model do
tax_line = order.tax_lines.reload.sole
expect(tax_line.amount).to eq(0)
expect(tax_line.taxability_reason).to eq('zero_rated')
- expect(tax_line.category_code).to eq('Z')
expect(tax_line.tax_rate).to eq(rate)
end
end
@@ -131,7 +129,6 @@ describe Spree::TaxProvider::Internal, type: :model do
tax_line = order.tax_lines.reload.sole
expect(tax_line.amount).to eq(0)
expect(tax_line.taxability_reason).to eq('customer_exempt')
- expect(tax_line.category_code).to eq('E')
expect(tax_line.data['exemption']).to eq('reason_code' => 'resale', 'certificate_number' => 'CERT-1')
end