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
Say what a tax engine's declared limits cost the merchant
Łukasz Adamczykdecb40335a41
diff --git a/docs/plans/6.0-tax-provider.md b/docs/plans/6.0-tax-provider.mdindex abd5d3c1e0..179cd4e025 100644--- a/docs/plans/6.0-tax-provider.md+++ b/docs/plans/6.0-tax-provider.md@@ -992,7 +992,7 @@ Serializer fields: `name`, `amount` (plus `amount_percentage`, the virtual the a| Endpoint | Purpose ||---|---|-| `GET /admin/tax_providers` | registry keys, names, `available_for_store?`, and `unsupported_capabilities` |+| `GET /admin/tax_providers` | registry keys, names, `available_for_store?`, and `unsupported_capabilities` — each limit as `{key, label, description}`, where the description states what the merchant loses rather than naming the feature, since the point of declaring it is the risk of under-collecting. Strings live in core's `spree.tax_capabilities.*`; a capability with none degrades to its humanized key, so an extension declaring its own reads sensibly before it ships translations || `PATCH /admin/markets/:id` | `tax_provider` becomes writable |The dashboard cannot build a provider dropdown, nor warn that Internal should not be paired with a US market, without the declarations reaching it. Note `/admin/markets` is currently `only: [:index, :show]` — Phase 4 adds `update`.diff --git a/spree/api/spec/controllers/spree/api/v3/admin/tax_providers_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/tax_providers_controller_spec.rbindex 215f78cf77..664e6b9927 100644--- a/spree/api/spec/controllers/spree/api/v3/admin/tax_providers_controller_spec.rb+++ b/spree/api/spec/controllers/spree/api/v3/admin/tax_providers_controller_spec.rb@@ -16,7 +16,19 @@ RSpec.describe Spree::Api::V3::Admin::TaxProvidersController, type: :controllerexpect(internal['name']).to eq('Internal')expect(internal['available']).to be(true)expect(internal['default']).to be(true)- expect(internal['unsupported_capabilities']).to contain_exactly('us_local_tax', 'reverse_charge', 'oss_thresholds')+ expect(internal['unsupported_capabilities'].map { |capability| capability['key'] }).to(+ contain_exactly('us_local_tax', 'reverse_charge', 'oss_thresholds')+ )+ end++ it 'gives each limit a label and the consequence a merchant can act on' do+ get :index, as: :json++ internal = json_response['data'].find { |provider| provider['id'] == 'Spree::TaxProvider::Internal' }+ reverse_charge = internal['unsupported_capabilities'].find { |c| c['key'] == 'reverse_charge' }++ expect(reverse_charge['label']).to eq('EU reverse charge')+ expect(reverse_charge['description']).to include('charged tax instead of receiving a zero-rated invoice')endit 'reports an engine whose credentials are missing as unavailable' dodiff --git a/spree/core/app/models/spree/tax_provider/base.rb b/spree/core/app/models/spree/tax_provider/base.rbindex 843d442123..2c7cbc6fb6 100644--- a/spree/core/app/models/spree/tax_provider/base.rb+++ b/spree/core/app/models/spree/tax_provider/base.rb@@ -37,6 +37,22 @@ module Spreename.demodulize.titleizeend+ # The declared limits with the strings a merchant can act on. A capability+ # with no translation degrades to its humanized key rather than a missing+ # translation, so an extension that declares one without shipping strings+ # still reads sensibly.+ #+ # @return [Array<Hash>]+ def self.unsupported_capability_details+ unsupported_capabilities.map do |capability|+ {+ key: capability.to_s,+ label: Spree.t("tax_capabilities.#{capability}.label", default: capability.to_s.humanize),+ description: Spree.t("tax_capabilities.#{capability}.description", default: nil)+ }.compact+ end+ end+# How this engine describes itself to the admin, mirroring# Spree::PreferenceSchema#subclasses_with_preference_schema: the class# being described owns its own presentation, not the controller.@@ -48,7 +64,7 @@ module Spreeid: name,name: display_name,available: available_for_store?(store),- unsupported_capabilities: unsupported_capabilities.map(&:to_s),+ unsupported_capabilities: unsupported_capability_details,default: name == Rails.application.config.spree.tax_provider.to_s}enddiff --git a/spree/core/config/locales/en.yml b/spree/core/config/locales/en.ymlindex 55ac0924c5..476fb6c2fe 100644--- a/spree/core/config/locales/en.yml+++ b/spree/core/config/locales/en.yml@@ -1513,6 +1513,16 @@ en:supported_locales: Supported Localestags: Tagstax: Tax+ tax_capabilities:+ oss_thresholds:+ description: Crossing the EU-wide cross-border threshold does not switch to destination-country rates automatically, because it depends on annual turnover across every destination rather than on any single order.+ label: Distance-selling thresholds+ reverse_charge:+ description: A VAT-registered business buyer is charged tax instead of receiving a zero-rated invoice. Their registration number is recorded but does not change the tax.+ label: EU reverse charge+ us_local_tax:+ description: County, city and district rates are not applied — only the rates configured per country or state. Sales into US states that levy local tax will be under-collected.+ label: US local taxtax_category: Tax Categorytax_code: Tax Codetax_inclusive: Tax inclusivediff --git a/spree/core/spec/models/spree/tax_provider/base_spec.rb b/spree/core/spec/models/spree/tax_provider/base_spec.rbindex e41fcbaf21..acce93d583 100644--- a/spree/core/spec/models/spree/tax_provider/base_spec.rb+++ b/spree/core/spec/models/spree/tax_provider/base_spec.rb@@ -44,15 +44,38 @@ describe Spree::TaxProvider::Base, type: :model dodescribe 'self-description for the admin' doit 'presents id, name, availability and limits' do- expect(Spree::TaxProvider::Internal.to_api_hash(order.store)).to eq(- id: 'Spree::TaxProvider::Internal',- name: 'Internal',- available: true,- unsupported_capabilities: %w[us_local_tax reverse_charge oss_thresholds],- default: true+ hash = Spree::TaxProvider::Internal.to_api_hash(order.store)++ expect(hash[:id]).to eq('Spree::TaxProvider::Internal')+ expect(hash[:name]).to eq('Internal')+ expect(hash[:available]).to be(true)+ expect(hash[:default]).to be(true)+ expect(hash[:unsupported_capabilities].map { |capability| capability[:key] }).to eq(+ %w[us_local_tax reverse_charge oss_thresholds])end+ it 'says what each limit costs the merchant, not just its name' do+ local_tax = Spree::TaxProvider::Internal.unsupported_capability_details.+ find { |capability| capability[:key] == 'us_local_tax' }++ expect(local_tax[:label]).to eq('US local tax')+ expect(local_tax[:description]).to include('County, city and district')+ end++ it 'falls back to a humanized key for a capability with no strings' do+ stub_const('SpecOddProvider', Class.new(described_class) do+ def self.unsupported_capabilities+ [:margin_scheme_goods]+ end+ end)++ capability = SpecOddProvider.unsupported_capability_details.sole++ expect(capability[:label]).to eq('Margin scheme goods')+ expect(capability).not_to have_key(:description)+ end+it 'lets a provider gem name itself rather than wear a mangled class name' dostub_const('SpreeTaxAvalara::TaxProvider', Class.new(described_class) dodef self.display_name