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.
Integrations Admin
Status: Implemented (2026-08-06) — see "Implementation status"
Target: Spree 6.0
Depends on: 6.0-delivery-rate-provider.md (EasyPost — the first real Integration consumer), 6.0-fulfillment-and-delivery.md (pickup point providers resolve credentials here), 6.0-tax-provider.md (Avalara Integration subclass). Coordinates with: 6.0-admin-api.md, 6.0-admin-spa.md, 5.5-admin-api-key-scopes.md (new read_integrations/write_integrations scopes)
Author: Damian + Claude
Last updated: 2026-08-06
Implementation status (2026-08-06)
Shipped in one wave, all suites green: PreferenceSchema on Spree::Integration with registers_subclasses_via over the (already existing) Spree.integrations registry, type-registration and verify-before-activate validations on the model, the unique (store_id, type) index, and read_integrations/write_integrations API-key scopes. Admin API v3: full CRUD via the shared SubclassedResource concern (registry-resolved types, typed preference setters, masked-secret round-trip guard for free), plus GET /integrations/types (gallery source with per-store connected) and POST /:id/test. SDK: adminClient.integrations with hand-written type/params definitions and the generated Integration type. Dashboard: /settings/integrations gallery grouped by integration_group with a connect/configure sheet (PreferencesForm, active toggle, inline test-connection, destructive-confirmed disconnect), settings-nav entry, i18n in all six locales. rswag coverage + regenerated OpenAPI/CLI specs.
Two notes beyond the design below: (1) the model's type-registration validation is skipped while the registry is empty — core ships no integrations, and the admin API resolves types through the registry regardless, so the escape keeps bare-core installs and factories working; (2) Spree::Integration.api_type derives the wire shorthand from the outer module for classes named exactly Integration (SpreeEasyPost::Integration → easy_post) — the gem convention makes demodulized names collide on integration.
Summary
Make Spree::Integration the single credential surface for every provider seam — delivery rates (EasyPost), tax (Avalara), fulfillment, pickup point networks (InPost), and future gateways of any kind — and give it the admin surface it has never had: an Admin API v3 resource plus a dashboard "Integrations" settings page where a merchant sees, in one place, everything connected to the current store. The model shipped in 5.x (spree_integrations: per-store, typed, preferences, active, can_connect?) but has zero subclasses in core, no registry, no API, and no UI — every capability on it is currently unexercised. This plan is the missing half: providers stay stateless strategy objects; Integrations own the credentials; the dashboard owns the visibility.
Key Decisions (do not deviate without discussion)
- One credential home. Provider gems ship an
Spree::Integrationsubclass holding credentials in model preferences, plus one or more stateless provider classes that resolve it viastore.integrations.active.find_by(type: ...). Providers never store credentials, and no new provider seam may invent its own credential storage (no env-var contracts, no preferences on the provider's host model). Existing exception: the Meilisearch search provider stays onMEILISEARCH_URLenv config for 6.0 — it is infrastructure shared across stores, not a per-store commerce credential; migrating it is out of scope. - Explicit registry:
Spree.integrations. Engine-defaulted array of class-name strings; gems append in an initializer (Spree.integrations << 'SpreeEasyPost::Integration'). Same shape asSpree.fulfillment_providers/Spree.delivery_method_rules. No descendants-scanning — eager-loading-dependent magic hides intent.Spree::Integrationvalidatestypeinclusion against the registry on attribute change. - Preference schema drives the UI.
Spree::Integrationincludes the existingSpree::PreferenceSchemaconcern. The types-discovery endpoint servesserialized_preference_schema; the dashboard renders forms with the existingPreferencesFormcomponent. Secrets use:password-typed preferences and flow through the existingSpree::Preferences::Maskingmachinery — masked on read (••••+ last 4), masked-round-trip-guarded on write, exactly as payment method credentials work today. - One integration per (store, type) stays (model validation shipped; this plan adds the backing unique DB index per house rule). Multi-account support is explicitly out of scope — same deferral as
6.0-payment-method-rules.md's per-channel credentials grooming note. - Admin-only surface. No store serializer, no storefront exposure, ever. Secret-key access is gated by new
read_integrations/write_integrationsscopes; JWT access by CanCanCan onSpree::Integration. - Verify before activate (resolved 2026-08-06). Saving credentials never runs a network call — partial setups save fine, inactive. Flipping
active: truerunscan_connect?and rejects with 422 (connection_error_messagein the error) on failure. Accepted trade-off: a vendor outage temporarily blocks going live (not editing); the explicitPOST /:id/testendpoint remains for diagnostics at any time. - Gallery branding is
logo_url+ server-localizeddescription(resolved 2026-08-06). Integration gems declare a class-levellogo_url— an absolute URL to hosted brand assets, or adata:URI for self-contained gems — and adescription(withspree.integrations.<api_type>.descriptionRails translations winning, so gems localize server-side; dashboard locale files are not extendable by Ruby gems). Deliberately not asset-pipeline paths: in the 6.0 split the Rails side is a data API — integration gems shipping browser images would force Propshaft onto headless hosts plus precompile hints and host-URL resolution. Accepted trade-off: hosted logos are a courtesy, not a guarantee (vendor CDNs rot, air-gapped admins) — the dashboard always falls back to a letter avatar, and self-contained gems use data URIs. - Connection status is ephemeral (resolved 2026-08-06). No
last_checked_at/last_errorcolumns — the test endpoint returns live results, the gallery shows stored state (active) plus on-demand test results. Accepted trade-off: no "last verified 2h ago" display without clicking test.
Design Details
Model additions (spree/core)
class Spree::Integration < Spree.base_class
include Spree::PreferenceSchema # preference_schema, serialized_preferences (masked)
validate :type_must_be_registered, if: :type_changed?
end
- Migration:
add_index :spree_integrations, [:store_id, :type], unique: true(backs the existing uniqueness validation). Spree.integrations/Spree.integrations=accessors overRails.application.config.spree.integrations(default[]).integration_group,integration_name,integration_key,icon_pathalready exist on the class — the types endpoint finally consumes them.
Admin API v3 (/api/v3/admin/integrations)
Standard Admin::ResourceController CRUD plus two extras:
| Endpoint | Purpose |
|---|---|
GET /integrations |
Connected integrations for the current store (Ransack: type, active) |
GET /integrations/types |
Registered types: type (wire shorthand via integration_key), name, group, icon, preference_schema (password defaults nilled), and connected for the current store — the dashboard's gallery source |
POST /integrations |
params.permit(:type, :active, preferences: {}) — flat params, type resolved from the wire shorthand against the registry only (never bare constantize) |
PATCH /integrations/:id |
Preferences merged with the masked-round-trip guard: a submitted value carrying the mask token keeps the stored secret. Activation (active: true, on create or update) runs can_connect? and 422s on failure per the verify-before-activate decision |
DELETE /integrations/:id |
Disconnect. Providers referencing it degrade per their own available_for_store? contract |
POST /integrations/:id/test |
Runs can_connect?; returns { connected:, error_message: } from connection_error_message. Never persisted |
Serializer (admin only): id, type (shorthand), name, group, active, preferences via serialized_preferences (masked), created_at/updated_at. Scope is current_store.integrations — cross-store ids 404.
Dashboard (/settings/integrations)
- Settings-nav entry in the existing settings registry;
<Can>-gated on integrations. - Gallery page: registered types grouped by
integration_group(shipping,tax, …, translated viaSpree.t-mirrored i18n keys), each card showing icon, name, and connected/active state — this is the "one page to see what is connected" the plan exists for. - Connect/configure sheet:
PreferencesFormrendered frompreference_schema, active toggle, "Test connection" button calling the test endpoint and surfacingerror_messageinline, destructive-confirmed disconnect. adminClient.integrationsresource in@spree/admin-sdk; full type-generation pipeline; i18n keys in all six locales.
Provider linkage
Each provider class declares self.integration_class and self.available_for_store?(store) (already specified in 6.0-delivery-rate-provider.md). Admin pickers (delivery-method provider select, tax provider select) filter on available_for_store? and deep-link to /settings/integrations when the wanted integration is not yet connected — the integrations page is the hub those flows land on.
Migration Path
- Core: registry +
PreferenceSchemainclude + type-inclusion validation + unique index migration. - Admin API: controller, serializer, scopes, integration specs (happy path) + controller specs (masking round-trip, cross-store 404, unregistered type rejection).
- SDK resource + generated types.
- Dashboard gallery + sheet + settings-nav entry + i18n.
- First consumers land with their own plans:
SpreeEasyPost::Integration(delivery-rate Phase 5) and Avalara (tax). Pickup point network integrations arrive in 6.1 at the earliest (pickup work deferred, decisions.md 2026-08-06 amendment).
No data migration — the table is empty in practice (zero core subclasses exist).
Constraints on Current Work
- New provider gems must ship an Integration subclass for credentials and register it in
Spree.integrations— no env-var credential contracts for per-store providers. - Secrets are
:password-typed preferences — anything else bypasses masking and will leak through the serializer. - Never
constantizea client-supplied integration type — resolve through the registry. - Don't build per-provider credential UIs (e.g. credentials card on the delivery-method sheet) — configuration lives on the integrations page; provider pickers link to it.
Open Questions
(resolved interactively 2026-08-06 — see Key Decisions; none remain)
References
- Model:
spree/core/app/models/spree/integration.rb; table:20250407085228_create_spree_integrations.rb - Schema/masking machinery:
spree/core/app/models/concerns/spree/preference_schema.rb,spree/core/lib/spree/core/preferences/masking.rb - Types-endpoint precedent:
spree/api/app/controllers/spree/api/v3/admin/payment_methods_controller.rb - Related plans:
6.0-delivery-rate-provider.md,6.0-fulfillment-and-delivery.md,6.0-tax-provider.md,6.0-payment-method-rules.md(multi-account deferral), decisions.md 2026-07-30 (reference providers), 2026-08-06 (EasyPost)