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.

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.md
index 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.rb
index 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: :controller
expect(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')
end
it 'reports an engine whose credentials are missing as unavailable' do
diff --git a/spree/core/app/models/spree/tax_provider/base.rb b/spree/core/app/models/spree/tax_provider/base.rb
index 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 Spree
name.demodulize.titleize
end
+ # 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 Spree
id: 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
}
end
diff --git a/spree/core/config/locales/en.yml b/spree/core/config/locales/en.yml
index 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 Locales
tags: Tags
tax: 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 tax
tax_category: Tax Category
tax_code: Tax Code
tax_inclusive: Tax inclusive
diff --git a/spree/core/spec/models/spree/tax_provider/base_spec.rb b/spree/core/spec/models/spree/tax_provider/base_spec.rb
index 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 do
describe 'self-description for the admin' do
it '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' do
stub_const('SpreeTaxAvalara::TaxProvider', Class.new(described_class) do
def self.display_name