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
Answer the tax registration question each endpoint is really asked
Łukasz Adamczyk33cf44eb37d4
diff --git a/docs/plans/6.0-tax-provider.md b/docs/plans/6.0-tax-provider.mdindex c887670909..5a0d7f6fc0 100644--- a/docs/plans/6.0-tax-provider.md+++ b/docs/plans/6.0-tax-provider.md@@ -328,7 +328,7 @@ endNote this is a validator's return type, not `estimate`'s — `estimate` writes rows and returns nothing meaningful.The Avalara gem registers a validator for the kinds Avalara can check. An EU extension registers one against the EU verification service — and can then add reverse charge on top of Internal by supplying only the treatment, since a verified identifier is the piece Internal lacks rather than the logic.-- **API surface:** singular nested resources on the customer account, the cart and (read-only) the order — see the API surface section for the endpoint list and the store/admin field split.+- **API surface:** singular nested resources on the customer account, the cart and (read-only) the order, on both the store and admin sides — see the API surface section for the endpoint list and the field split. The cart endpoint *reads* the resolved registration (override, else the customer's) because that is what the provider will be handed, while writes and deletes touch the cart's own row only: a cleared checkout field must not delete a customer's profile registration.- **Provider consumption:** the provider reads `kind` and `value`, never the ownership FKs and never the verdict. Avalara maps to `businessIdentificationNo` (the B2B-VAT-rules switch), Stripe to `tax_ids`; both revalidate server-side regardless. The Internal provider ignores the identifier entirely — reverse charge is on its declared-unsupported list, and charging normal tax when no validated ID is present is the legally safe default: for services, treating an unidentified buyer as a consumer is a presumption EU law explicitly protects, and for goods a valid ID has been a hard condition of zero-rating since 2020.### Tax exemption is a typed estimate input plus a TaxLine output — not a boolean, not a hookdiff --git a/spree/api/app/controllers/spree/api/v3/admin/orders/tax_identifiers_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/orders/tax_identifiers_controller.rbnew file mode 100644index 0000000000..aab36b960f--- /dev/null+++ b/spree/api/app/controllers/spree/api/v3/admin/orders/tax_identifiers_controller.rb@@ -0,0 +1,41 @@+module Spree+ module Api+ module V3+ module Admin+ module Orders+ # The registration the order was taxed against, frozen at completion.+ # Read-only because the row is: staff investigating why an invoice was+ # zero-rated need to see the number and the verdict behind it, not+ # change what the invoice already says.+ class TaxIdentifiersController < BaseController+ # A singular nested resource: there is no :id to look up, and the+ # inherited lookup would reach for a plural association that does+ # not exist. Mirrors Orders::StoreCreditsController.+ skip_before_action :set_resource, raise: false++ scoped_resource :orders++ # GET /api/v3/admin/orders/:order_id/tax_identifier+ def show+ return head :not_found if @parent.tax_identifier.nil?++ authorize_resource!(@parent.tax_identifier, :show)++ render json: serialize_resource(@parent.tax_identifier)+ end++ protected++ def model_class+ Spree::TaxIdentifier+ end++ def serializer_class+ Spree.api.admin_tax_identifier_serializer+ end+ end+ end+ end+ end+ end+enddiff --git a/spree/api/app/controllers/spree/api/v3/store/carts/tax_identifiers_controller.rb b/spree/api/app/controllers/spree/api/v3/store/carts/tax_identifiers_controller.rbindex d4afd89a5a..cf6ed8aef5 100644--- a/spree/api/app/controllers/spree/api/v3/store/carts/tax_identifiers_controller.rb+++ b/spree/api/app/controllers/spree/api/v3/store/carts/tax_identifiers_controller.rb@@ -12,10 +12,16 @@ module Spreebefore_action :find_cart!# GET /api/v3/store/carts/:cart_id/tax_identifier+ #+ # The registration this cart will be taxed against — the override+ # when one was entered, the customer's own otherwise. A checkout page+ # asking what applies wants the answer the provider will get, not+ # whether an override happens to exist.def show- return head :not_found if @cart.tax_identifier.nil?+ resolved = @cart.resolved_tax_identifier+ return head :not_found if resolved.nil?- render json: serialize_resource(@cart.tax_identifier)+ render json: serialize_resource(resolved)end# PUT /api/v3/store/carts/:cart_id/tax_identifier@@ -25,7 +31,7 @@ module Spreeif resource.save# Tax depends on the registration, so the cart has to be re-costed.- Spree.cart_recalculate_totals_workflow.call(cart: @cart)+ @cart.recalculate_totals!render json: serialize_resource(resource), status: resource.previously_new_record? ? :created : :okelserender_validation_error(resource.errors)@@ -33,11 +39,16 @@ module Spreeend# DELETE /api/v3/store/carts/:cart_id/tax_identifier+ #+ # Clears the override only. The customer's own registration is theirs+ # to remove from their profile — a cleared checkout field must not+ # delete it — so a cart with no override of its own reports nothing+ # to delete even when GET returns an inherited one.def destroyreturn head :not_found if @cart.tax_identifier.nil?@cart.tax_identifier.destroy!- Spree.cart_recalculate_totals_workflow.call(cart: @cart.reload)+ @cart.reload.recalculate_totals!head :no_contentenddiff --git a/spree/api/config/routes.rb b/spree/api/config/routes.rbindex 94daf9d843..bcd8b13f60 100644--- a/spree/api/config/routes.rb+++ b/spree/api/config/routes.rb@@ -497,6 +497,8 @@ Spree::Core::Engine.add_routes doendresources :refunds, controller: 'orders/refunds', only: [:index, :create]resources :tax_lines, controller: 'orders/tax_lines', only: [:index, :show]+ # Read-only — the registration frozen onto the order at completion.+ resource :tax_identifier, controller: 'orders/tax_identifiers', only: [:show]resources :discounts, controller: 'orders/discounts', only: [:index, :show, :create, :update, :destroy]resources :discount_codes, controller: 'orders/discount_codes', only: [:create, :destroy]resources :fees, controller: 'orders/fees', only: [:index, :show, :create, :update, :destroy]diff --git a/spree/api/spec/controllers/spree/api/v3/admin/orders/tax_identifiers_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/orders/tax_identifiers_controller_spec.rbnew file mode 100644index 0000000000..a6bfbae317--- /dev/null+++ b/spree/api/spec/controllers/spree/api/v3/admin/orders/tax_identifiers_controller_spec.rb@@ -0,0 +1,49 @@+require 'spec_helper'++RSpec.describe Spree::Api::V3::Admin::Orders::TaxIdentifiersController, type: :controller do+ render_views++ include_context 'API v3 Admin authenticated'++ let!(:order) { create(:completed_order_with_totals, store: store) }++ before { request.headers.merge!(headers) }++ describe 'GET #show' do+ it 'returns the snapshot with the verdict and the evidence behind it' do+ create(:tax_identifier, :on_order, :verified, order: order, kind: 'eu_vat', value: 'DE123456789')++ get :show, params: { order_id: order.prefixed_id }, as: :json++ expect(response).to have_http_status(:ok)+ expect(json_response['kind']).to eq('eu_vat')+ expect(json_response['value']).to eq('DE123456789')+ # The fields the store serializer withholds — why staff come here.+ expect(json_response['validation_status']).to eq('verified')+ expect(json_response['validation_evidence']['registry']).to eq('vies')+ expect(json_response['source']).to eq('customer')+ expect(json_response['order_id']).to eq(order.prefixed_id)+ end++ it '404s on a consumer sale, which carries no registration' do+ get :show, params: { order_id: order.prefixed_id }, as: :json++ expect(response).to have_http_status(:not_found)+ end++ it '404s on an order from another store' do+ other_order = create(:completed_order_with_totals, store: create(:store))+ create(:tax_identifier, :on_order, order: other_order)++ get :show, params: { order_id: other_order.prefixed_id }, as: :json++ expect(response).to have_http_status(:not_found)+ end+ end++ it 'does not route a write — the snapshot is what the invoice says' do+ expect {+ patch :update, params: { order_id: order.prefixed_id, value: 'DE999999999' }, as: :json+ }.to raise_error(ActionController::UrlGenerationError)+ end+enddiff --git a/spree/api/spec/requests/spree/api/v3/store/tax_identifiers_spec.rb b/spree/api/spec/requests/spree/api/v3/store/tax_identifiers_spec.rbindex 4f56493571..350c24457c 100644--- a/spree/api/spec/requests/spree/api/v3/store/tax_identifiers_spec.rb+++ b/spree/api/spec/requests/spree/api/v3/store/tax_identifiers_spec.rb@@ -33,6 +33,48 @@ RSpec.describe 'Store tax identifiers', type: :request dodescribe 'a checkout override on the cart' dolet(:cart) { create(:cart_with_line_items, line_items_count: 1, store: store, customer: user) }+ it 'reads the customer registration when the cart has no override' do+ create(:tax_identifier, customer: user, kind: 'eu_vat', value: 'DE123456789')++ get "/api/v3/store/carts/#{cart.prefixed_id}/tax_identifier",+ headers: headers.merge('x-spree-token' => cart.token), as: :json++ # What the provider will be handed, which is the question a checkout asks.+ expect(response).to have_http_status(:ok)+ expect(JSON.parse(response.body)['value']).to eq('DE123456789')+ end++ it 'prefers the cart override over the customer registration' do+ create(:tax_identifier, customer: user, kind: 'eu_vat', value: 'DE123456789')+ create(:tax_identifier, customer: nil, cart: cart, kind: 'eu_vat', value: 'DE999999999')++ get "/api/v3/store/carts/#{cart.prefixed_id}/tax_identifier",+ headers: headers.merge('x-spree-token' => cart.token), as: :json++ expect(JSON.parse(response.body)['value']).to eq('DE999999999')+ end++ it 'clears only the override, leaving the customer registration alone' do+ profile = create(:tax_identifier, customer: user, kind: 'eu_vat', value: 'DE123456789')+ create(:tax_identifier, customer: nil, cart: cart, kind: 'eu_vat', value: 'DE999999999')++ delete "/api/v3/store/carts/#{cart.prefixed_id}/tax_identifier",+ headers: headers.merge('x-spree-token' => cart.token), as: :json++ expect(response).to have_http_status(:no_content)+ expect(profile.reload).to be_present+ expect(cart.reload.tax_identifier).to be_nil+ end++ it 'has nothing of its own to delete when the registration is inherited' do+ create(:tax_identifier, customer: user, kind: 'eu_vat', value: 'DE123456789')++ delete "/api/v3/store/carts/#{cart.prefixed_id}/tax_identifier",+ headers: headers.merge('x-spree-token' => cart.token), as: :json++ expect(response).to have_http_status(:not_found)+ end+it 'is stored against the cart and read back' doput "/api/v3/store/carts/#{cart.prefixed_id}/tax_identifier",params: { kind: 'eu_vat', value: 'DE555555555' },