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
Update tax/delivery provider plans on provider <> integration model usage
Damian Legawiec589cba9fe298
diff --git a/docs/plans/6.0-delivery-rate-provider.md b/docs/plans/6.0-delivery-rate-provider.mdindex c81f7f89e7..359f0ee06d 100644--- a/docs/plans/6.0-delivery-rate-provider.md+++ b/docs/plans/6.0-delivery-rate-provider.md@@ -4,7 +4,7 @@**Target:** Spree 6.0**Depends on:** Fulfillment & Delivery (6.0-fulfillment-and-delivery.md) for DeliveryMethod rename**Author:** Damian + Claude-**Last updated:** 2026-03-22+**Last updated:** 2026-04-05## Summary@@ -100,9 +100,72 @@ provider.estimate_rates(package, delivery_methods)The Internal provider wraps each `calculator.compute(package)` result in a `DeliveryRateEstimate` with no carrier/service metadata (same as today).+### Credentials live in Spree::Integration, not the provider++Providers are stateless strategy objects — they define behavior (estimate rates). They do **not** store credentials. API keys, secrets, and connection config for external services live in `Spree::Integration` subclasses, which provide:++- **Per-store persistence** — credentials stored in the `preferences` column+- **Admin UI** — dynamic forms for non-developer configuration+- **Connection validation** — `can_connect?` hook tests credentials before saving+- **Activation tracking** — `active` boolean flag++A provider gem (e.g., `spree_easypost`) ships **both** an Integration subclass and a Provider subclass:++```ruby+# Integration — stores credentials, provides admin UI+class Spree::Integrations::EasyPost < Spree::Integration+ preference :api_key, :string+ preference :mode, :string, default: 'test' # test or production++ def self.integration_group = 'shipping'++ def can_connect?+ EasyPost::Client.new(api_key: preferred_api_key).address.create(+ street1: '417 Montgomery St', city: 'San Francisco', state: 'CA', zip: '94104', country: 'US'+ )+ true+ rescue => e+ self.connection_error_message = e.message+ false+ end+end++# Provider — behavioral contract, reads credentials from Integration at runtime+class SpreeEasyPost::DeliveryRateProvider < Spree::DeliveryRateProvider::Base+ def self.integration_class = 'Spree::Integrations::EasyPost'++ def self.available_for_store?(store)+ store.integrations.active.exists?(type: integration_class)+ end++ def estimate(package)+ # ... rate calculation using client ...+ end++ private++ def client+ @client ||= begin+ store = delivery_method.stores.first # or however the method resolves its store+ integration = store.integrations.active.find_by!(type: self.class.integration_class)+ EasyPost::Client.new(api_key: integration.preferred_api_key)+ end+ end+end+```++**Admin flow:**+1. Admin navigates to Integrations → connects EasyPost (enters API key, tests connection)+2. Admin navigates to DeliveryMethod "Standard Shipping" → selects "EasyPost" as rate provider+3. At runtime, the provider reads credentials from the Integration record++**Internal providers don't need an Integration.** `Spree::DeliveryRateProvider::Internal` reads DeliveryMethod pricing preferences directly — no external credentials.++**Provider availability depends on Integration status.** The DeliveryMethod admin UI should only offer providers whose Integration is active for that store.+### Provider is per delivery method-Unlike search (global) and tax (per-store), delivery rate providers are **per delivery method**. One store can have:+Unlike search (global) and tax (per-market), delivery rate providers are **per delivery method**. One store can have:- "Free Shipping" → `Spree::DeliveryRateProvider::Internal` (flat rate: $0)- "Standard Shipping" → `SpreeEasyPost::DeliveryRateProvider` (UPS Ground rates)@@ -231,11 +294,17 @@ end### External Provider Example (EasyPost)-Each EasyPost-backed DeliveryMethod stores its carrier + service in metadata:+Each EasyPost-backed DeliveryMethod stores its carrier + service in metadata. Note how the provider reads credentials from its `Spree::Integration` record (see "Credentials live in Spree::Integration" above):```rubymodule SpreeEasyPostclass DeliveryRateProvider < Spree::DeliveryRateProvider::Base+ def self.integration_class = 'Spree::Integrations::EasyPost'++ def self.available_for_store?(store)+ store.integrations.active.exists?(type: integration_class)+ end+def estimate(package)# Get rate for this specific carrier+service from EasyPostshipment = find_or_create_easypost_shipment(package)@@ -259,11 +328,19 @@ module SpreeEasyPostprivate+ def client+ @client ||= begin+ store = delivery_method.stores.first+ integration = store.integrations.active.find_by!(type: self.class.integration_class)+ EasyPost::Client.new(api_key: integration.preferred_api_key)+ end+ end+# Cache the EasyPost shipment per package to avoid duplicate API calls# (multiple DeliveryMethods may share the same EasyPost provider)def find_or_create_easypost_shipment(package)cache_key = "easypost_shipment_#{package.stock_location.id}_#{package.order.id}"- RequestStore.store[cache_key] ||= EasyPost::Shipment.create(+ RequestStore.store[cache_key] ||= client.shipment.create(from_address: address_from_stock_location(package.stock_location),to_address: address_from_order(package.order),parcel: parcel_from_package(package)@@ -370,6 +447,9 @@ Established the pattern. All three follow the same open-closed architecture:| **Internal** | Database (SQL) | Reads TaxRate data directly | Reads DeliveryMethod prefs directly || **External** | Meilisearch | Avalara / TaxJar | EasyPost / Shippo || **Calculators** | N/A | Removed in 6.0 | Removed in 6.0 |+| **Credentials** | `Spree::Integration` | `Spree::Integration` | `Spree::Integration` |++All external providers follow the same credential pattern: credentials live in a `Spree::Integration` subclass (per-store, admin-managed), the provider reads them at runtime. See "Credentials live in Spree::Integration" section above.### DeliveryZone replaces Zone for shippingdiff --git a/docs/plans/6.0-tax-provider.md b/docs/plans/6.0-tax-provider.mdindex 2eb8dac9bf..a5c7c8643d 100644--- a/docs/plans/6.0-tax-provider.md+++ b/docs/plans/6.0-tax-provider.md@@ -4,7 +4,7 @@**Target:** Spree 6.0**Depends on:** Split Adjustments (6.0-split-adjustments.md) for TaxLine model, Channels/Catalogs/B2B (6.0-channels-catalogs-b2b.md) for Company.tax_exempt**Author:** Damian + Claude-**Last updated:** 2026-03-22+**Last updated:** 2026-04-05## Summary@@ -104,6 +104,79 @@ With the split-adjustments plan (6.0), tax results are written as `Spree::TaxLinBefore split-adjustments ships, the provider writes `Spree::Adjustment` records (backward compatible).+### Credentials live in Spree::Integration, not the provider++Providers are stateless strategy objects — they define behavior (estimate, commit, void). They do **not** store credentials. API keys, secrets, and connection config for external services live in `Spree::Integration` subclasses, which provide:++- **Per-store persistence** — credentials stored in the `preferences` column+- **Admin UI** — dynamic forms for non-developer configuration+- **Connection validation** — `can_connect?` hook tests credentials before saving+- **Activation tracking** — `active` boolean flag++A provider gem (e.g., `spree_tax_avalara`) ships **both** an Integration subclass and a Provider subclass:++```ruby+# Integration — stores credentials, provides admin UI+class Spree::Integrations::Avalara < Spree::Integration+ preference :api_key, :string+ preference :environment, :string, default: 'sandbox'+ preference :company_code, :string++ def self.integration_group = 'tax'++ def can_connect?+ client = AvaTax::Client.new(api_key: preferred_api_key, environment: preferred_environment)+ client.ping.success?+ rescue => e+ self.connection_error_message = e.message+ false+ end+end++# Provider — behavioral contract, reads credentials from Integration at runtime+class SpreeTaxAvalara::TaxProvider < Spree::TaxProvider::Base+ def estimate(order, items)+ # ...+ response = client.create_transaction(request)+ # ...+ end++ private++ def client+ @client ||= begin+ integration = market.store.integrations.active.find_by!(type: 'Spree::Integrations::Avalara')+ AvaTax::Client.new(+ api_key: integration.preferred_api_key,+ environment: integration.preferred_environment+ )+ end+ end+end+```++**Admin flow:**+1. Admin navigates to Integrations → connects Avalara (enters API key, tests connection)+2. Admin navigates to Market "US" → selects "Avalara" as tax provider+3. At runtime, the provider reads credentials from the Integration record++**Internal providers don't need an Integration.** `Spree::TaxProvider::Internal` reads TaxRate records directly — no external credentials.++**Provider availability depends on Integration status.** The Market admin UI should only offer providers whose Integration is active. Provider classes declare their dependency:++```ruby+class SpreeTaxAvalara::TaxProvider < Spree::TaxProvider::Base+ def self.integration_class+ 'Spree::Integrations::Avalara'+ end++ # Internal providers override to always return true+ def self.available_for_store?(store)+ store.integrations.active.exists?(type: integration_class)+ end+end+```+### Provider is per-MarketMarkets represent regional commerce operations. Each market can have its own tax provider, matching how Shopify and Medusa handle it:@@ -159,13 +232,13 @@ State-level rates override country-level (more specific wins). A rate with `counThe generic `Spree::Zone` model is **dropped entirely** in 6.0. A data migration (rake task) converts existing Zone records into `TaxRate` country/state FKs (for tax) and `DeliveryZone` records (for shipping, see `6.0-delivery-rate-provider.md`). After migration, `spree_zones` and `spree_zone_members` tables are removed.-This matches the natural scope hierarchy:+This matches the natural scope hierarchy (all external providers store credentials in `Spree::Integration` — see above):-| Provider | Scope | Why |-|---|---|---|-| Search | Global (`Spree.search_provider`) | One search engine per instance |-| Tax | Per-Market (`Market#tax_provider`) | Different tax rules/services per region |-| Delivery rates | Per-DeliveryMethod (`DeliveryMethod#rate_provider`) | Different carriers per shipping option |+| Provider | Scope | Credentials | Why |+|---|---|---|---|+| Search | Global (`Spree.search_provider`) | `Spree::Integration` | One search engine per instance |+| Tax | Per-Market (`Market#tax_provider`) | `Spree::Integration` | Different tax rules/services per region |+| Delivery rates | Per-DeliveryMethod (`DeliveryMethod#rate_provider`) | `Spree::Integration` | Different carriers per shipping option |### Tax exemption is part of the provider contract@@ -308,11 +381,17 @@ end### External Provider Example (Avalara)-Shows the contract — actual implementation in `spree_tax_avalara` gem:+Shows the contract — actual implementation in `spree_tax_avalara` gem. Note how the provider reads credentials from its `Spree::Integration` record (see "Credentials live in Spree::Integration" above):```rubymodule SpreeTaxAvalaraclass TaxProvider < Spree::TaxProvider::Base+ def self.integration_class = 'Spree::Integrations::Avalara'++ def self.available_for_store?(store)+ store.integrations.active.exists?(type: integration_class)+ end+def estimate(order, items)return clear_tax(order, items) if exempt?(order)@@ -371,6 +450,19 @@ module SpreeTaxAvalarafalseendend++ private++ def client+ @client ||= begin+ integration = market.store.integrations.active.find_by!(type: self.class.integration_class)+ AvaTax::Client.new(+ api_key: integration.preferred_api_key,+ environment: integration.preferred_environment,+ company_code: integration.preferred_company_code+ )+ end+ endendend```