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.

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.md
index c887670909..5a0d7f6fc0 100644
--- a/docs/plans/6.0-tax-provider.md
+++ b/docs/plans/6.0-tax-provider.md
@@ -328,7 +328,7 @@ end
Note 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 hook
diff --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.rb
new file mode 100644
index 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
+end
diff --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.rb
index 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 Spree
before_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 Spree
if 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 : :ok
else
render_validation_error(resource.errors)
@@ -33,11 +39,16 @@ module Spree
end
# 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 destroy
return 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_content
end
diff --git a/spree/api/config/routes.rb b/spree/api/config/routes.rb
index 94daf9d843..bcd8b13f60 100644
--- a/spree/api/config/routes.rb
+++ b/spree/api/config/routes.rb
@@ -497,6 +497,8 @@ Spree::Core::Engine.add_routes do
end
resources :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.rb
new file mode 100644
index 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
+end
diff --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.rb
index 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 do
describe 'a checkout override on the cart' do
let(: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' do
put "/api/v3/store/carts/#{cart.prefixed_id}/tax_identifier",
params: { kind: 'eu_vat', value: 'DE555555555' },