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.

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.md
index 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):
```ruby
module SpreeEasyPost
class 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 EasyPost
shipment = find_or_create_easypost_shipment(package)
@@ -259,11 +328,19 @@ module SpreeEasyPost
private
+ 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 shipping
diff --git a/docs/plans/6.0-tax-provider.md b/docs/plans/6.0-tax-provider.md
index 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::TaxLin
Before 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-Market
Markets 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 `coun
The 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):
```ruby
module SpreeTaxAvalara
class 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 SpreeTaxAvalara
false
end
end
+
+ 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
+ end
end
end
```