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 delivery plans: EasyPost reference provider, Integrations Admin, pickup deferral

Damian Legawiecbeda6c43f036
diff --git a/CLAUDE.md b/CLAUDE.md
index 6f7383839f..58f48b7391 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -21,12 +21,13 @@ Active plans (6.0 target, work pending):
- `6.0-remove-master-variant.md` — Eliminate is_master, add default_variant_id FK on Product. **Shipped to 6-0-dev (PR #14265):** is_master removed from all models, default_variant_id + `spree:remove_master_variant` data-migration rake landed; only the physical is_master column drop remains (6.1 cleanup).
- `6.0-typed-stock-movements.md` — Replace generic StockMovement with typed kinds + concrete FKs
- `6.0-normalize-state-to-status.md` — Rename state → status on Payment, Shipment, InventoryUnit, ReturnAuthorization, GiftCard
-- `6.0-fulfillment-and-delivery.md` — Shipment→Fulfillment, ShippingMethod→DeliveryMethod, drop ShippingCategory, FulfillmentProvider strategy, pickup (merchant StockLocation) + pickup_point (third-party PickupPointProvider). **Shipped to 6-0-dev (Waves 2+4+6):** renames + deprecated twins, providers (Manual/Digital/Pickup/PickupPoint), dual-emit events, store pickup discovery endpoints, admin delivery_methods/delivery_zones CRUD + dashboard settings pages, FulfillmentMailer; Wave 7 shipping→delivery data migration remains
+- `6.0-fulfillment-and-delivery.md` — Shipment→Fulfillment, ShippingMethod→DeliveryMethod, drop ShippingCategory, FulfillmentProvider strategy, pickup (merchant StockLocation) + pickup_point (third-party PickupPointProvider). **Shipped to 6-0-dev (Waves 2+4+6):** renames + deprecated twins, providers (Manual/Digital/Pickup/PickupPoint), dual-emit events, store pickup discovery endpoints, admin delivery_methods/delivery_zones CRUD + dashboard settings pages, FulfillmentMailer; Wave 7 shipping→delivery data migration remains. Pickup work beyond shipped code deferred to 6.1 (2026-08-06): contract hardening (`new(delivery_method)` ctor, `find_nearby` zipcode/query) + how-to guide; `PickupPointProvider::Base` stays **undocumented in 6.0** (v6 docs cover only the delivery rate provider interface) — never add pickup-provider docs in 6.0 work. 6.0 built-in fulfillment types: `shipping`/`pickup`/`digital` — `pickup_point` unregistered until 6.1, `local_delivery` cut (= shipping + postal-code zone)
- `6.0-returns-exchanges-claims.md` — First-class Return, Exchange, Claim models replacing ReturnAuthorization/Reimbursement chain. **COMPLETE (2026-08-05):** all three entities (+ permanent `ReturnLineItem`/`ExchangeLineItem`/`ClaimLineItem` line items), `Spree::HasStatus`, all fifteen workflows (each with a leading `validate` hook), `Refund#originator`, admin + store v3 APIs (transitions as PATCH member actions; no destroy — cancel instead), dashboard pages. Legacy chain **removed**: ReturnAuthorization/CustomerReturn/Reimbursement/ReimbursementType/legacy ReturnItem + eligibility validators + ReturnsCalculator classes all deleted, but their **tables deliberately survive to 6.1** as the data migration's source and rollback path. `spree:upgrade:migrate_returns` (`Spree::ReturnsMigrator`, defined in the rake file like its sibling upgrade tasks; anonymous-AR readers) is in the 5.6→6.0 manifest after the adjustments step; it needs no cursor because the preserved `number` is uniquely indexed on the new tables, so "what's left" is a `where.not(number: ...)` query and an interrupted run resumes for free. `ReturnAuthorizationReason`→`ReturnReason` (alias one release) + new `ClaimReason`; `Metafields` on all three. Capability replacements: `Spree::ReturnMailer#refunded_email` on `return.refunded` (replaces the reimbursement email), `Order#outstanding_balance` drops the reimbursement term (refunds already net out of `payment_total`), `Return#refunded_total` counts store credits too, `StoreCreditCategory.default_refund_category` (alias kept). **Reasons** ship admin-only CRUD (`/api/v3/admin/{return,claim,refund}_reasons`, `settings` scope) + a combined Settings → Reasons dashboard page + reason pickers on the create dialogs; `mutable` is never client-writable and the immutability guard lives on `Spree::NamedType` (`can_be_deleted?` + rename/destroy guards) because secret API keys authorize by scope and never consult CanCanCan. **No state machines (2026-08-02):** plain `status` string + inclusion validation; all fifteen transitions are workflows (`Returns::Receive`, `Exchanges::Fulfill`, `Claims::Resolve`, …) with `validate` hooks for return-eligibility policy and refunds as `external_step`. Nothing happens in a model or transition callback. Statuses live in a `class_attribute` via the core `Spree::HasStatus` concern (`has_status` + additive `add_status(value, after:)`, generating predicates and scopes) — extensible by design, additive only, and no transition graph (that would be a state machine again). **Return eligibility is a hook, not a policy engine (2026-08-03):** no window/restocking-fee/final-sale flag in core — a `validate` handler decides, enforcing for customers while letting staff override (it reads `created_by`), and region-varying policy reads `order.market`. Medusa/Saleor/Vendure ship no policy at all; Shopify's engine has no API. A `ReturnPolicy` model can arrive later behind the same hook.
- `6.0-platform-auth.md` — Drop Devise, own auth stack, User→Customer/Staff rename (RefreshToken shipped in 5.4)
- `6.0-tax-provider.md` — Per-Market TaxProvider, replaces TaxRate.adjust + Calculator; TaxRate gets direct country/state FKs (tax decoupled from Zone; Zone model dropped in 6.0 via `6.0-delivery-zones.md`); reference provider: Avalara (decisions.md 2026-07-30)
-- `6.0-delivery-rate-provider.md` — Per-DeliveryMethod DeliveryRateProvider wrapping Stock::Estimator (calculators stay — 2026-07-27 reversal), `store_id` on ShippingMethod, enriched DeliveryRate (carrier/service/date/metadata); monorepo ships one reference multi-carrier provider (Shippo/EasyPost, pick pending — decisions.md 2026-07-29); method rows stay regional (no cross-market method entity)
+- `6.0-delivery-rate-provider.md` — Per-DeliveryMethod DeliveryRateProvider wrapping Stock::Estimator (calculators stay — 2026-07-27 reversal), `store_id` on ShippingMethod, enriched DeliveryRate (carrier/service/date/metadata); monorepo ships one reference multi-carrier provider (**EasyPost** — decisions.md 2026-08-06 reversal: BYOCA fit for larger merchants + only maintained official Ruby SDK; Shippo's ruby gem dead since 2020); method rows stay regional (no cross-market method entity)
- `6.0-delivery-zones.md` — Zone → DeliveryZone with postal-code-range/prefix members (country-scoped); owns the full ~183-reference Zone consumer inventory; `Spree::Zone` dropped entirely by end of 6.0 (2026-07-27 — 6.0 is the breaking-change window)
+- `6.0-integrations-admin.md` — `Spree::Integration` as the single credential surface for all provider seams (delivery rates/tax/fulfillment/pickup points): explicit `Spree.integrations` registry, Admin API v3 CRUD + types discovery (reusing `PreferenceSchema`/`Masking` — secrets are `:password` preferences), dashboard `/settings/integrations` gallery grouped by `integration_group`. Verify-before-activate (`active: true` runs `can_connect?`, 422 on failure), ephemeral connection status. Constraints now: provider gems ship an Integration subclass (no env-var credential contracts for per-store providers); no per-provider credential UIs — pickers deep-link to the integrations page.
- `6.0-rich-text-descriptions.md` — Drop ActionText **entirely** at 6.0 (incl. CustomFields::RichText values + Order/User internal notes; gem dependency removed), store sanitized HTML in text columns, serve `field` + `field_html`, **write via `field_html`** (read/write symmetry). description_html serializer shipped 5.4; sanitizer shipped in **5.6.2** with a permissive-but-safe configurable allowlist + `sanitize_rich_text` step in the 5.5→5.6 upgrade manifest (decisions.md 2026-07-27/28), tightened to the Tiptap set at 6.0
- `6.0-inventory-operations.md` — StockTransfer lifecycle (draft → ready_to_ship → in_transit → received with partial receive), new `Spree::PurchaseOrder` + `Spree::Supplier` (renamed from Vendor — `Spree::Vendor` is the marketplace seller, see decisions.md 2026-07-14) replacing today's "external receive" hack, variant + stock-location stock history panels. Consumes the typed-movement primitives from `6.0-typed-stock-movements.md`.
- `6.0-replace-taxons-with-categories.md` — Split Taxon into Category (hierarchy) + Collection (flat/rule-based). **Shipped to 6-0-dev (PR #14302):** the Category surface (5.5–5.6) plus the 6.0 core — `spree_taxons`→`spree_categories` table rename + inheritance flip (`Spree::Category < Spree.base_class`, `Spree::Taxon` alias kept), the full `Collection` stack (model + rules + DB/Meilisearch manual sort + API), the taxon→category/collection data migration, and de-ruling Category. Pending (all 6.1): channel-aware `CollectionRules::AvailableOn` (ships interim now, rides with channels) + dropping `spree_taxon_rules`/`Taxonomy`. No brand feature in 6.0 — brands are modeled as a Category/Collection; `brand_taxon`/`brand_name` removed with `Taxonomy`.
diff --git a/docs/plans/6.0-admin-api.md b/docs/plans/6.0-admin-api.md
index 1f9339f3fb..d94b2de80b 100644
--- a/docs/plans/6.0-admin-api.md
+++ b/docs/plans/6.0-admin-api.md
@@ -747,7 +747,7 @@ API key scopes: `read_vendors` / `write_vendors`, `read_commissions` / `write_co
- [ ] `PATCH /api/v3/admin/delivery_methods/:id`
- [ ] `DELETE /api/v3/admin/delivery_methods/:id`
-> **6.0:** No more `calculator_id`. New fields: `rate_provider` (class name), `fulfillment_provider` (class name), `pickup_point_provider` (for third-party pickup), `fulfillment_type` (enum: `shipping`, `pickup`, `pickup_point`, `digital`, `local_delivery`). See `6.0-delivery-rate-provider.md`, `6.0-fulfillment-and-delivery.md`.
+> **6.0:** No more `calculator_id`. New fields: `rate_provider` (class name), `fulfillment_provider` (class name), `pickup_point_provider` (for third-party pickup), `fulfillment_type` (registered set — 6.0 built-ins: `shipping`, `pickup`, `digital`; `pickup_point` deferred to 6.1, `local_delivery` cut — decisions.md 2026-08-06). See `6.0-delivery-rate-provider.md`, `6.0-fulfillment-and-delivery.md`.
### Delivery Zones (new in 6.0, replaces shipping Zones)
- [ ] `GET /api/v3/admin/delivery_zones`
diff --git a/docs/plans/6.0-delivery-rate-provider.md b/docs/plans/6.0-delivery-rate-provider.md
index b0b956e6b5..7616962953 100644
--- a/docs/plans/6.0-delivery-rate-provider.md
+++ b/docs/plans/6.0-delivery-rate-provider.md
@@ -1,10 +1,10 @@
# Delivery Rate Provider Interface
-**Status:** Draft
+**Status:** Phases 1–4 shipped (see "Implementation status"); Phase 5 (the EasyPost gem) pending. Reference aggregator: **EasyPost** (decisions.md 2026-08-06 — Shippo pick reversed same day: BYOCA fit for larger merchants + the only actively maintained official Ruby SDK)
**Target:** Spree 6.0
**Depends on:** Fulfillment & Delivery (6.0-fulfillment-and-delivery.md) for the DeliveryMethod/DeliveryRate rename. Coordinates with: `6.0-multi-vendor-marketplace.md` (vendor-scoped method filtering — this plan owns the filter), `6.0-cart-order-split.md` (where estimation is invoked pre-completion), `5.6-6.0-single-store-promotions-payment-methods.md` (single-store pattern reused for `store_id`)
**Author:** Damian + Claude
-**Last updated:** 2026-07-29
+**Last updated:** 2026-08-06
## Summary
@@ -14,6 +14,22 @@ This follows the same open-closed provider pattern as `SearchProvider` (shipped
**Calculators are kept.** An earlier draft of this plan proposed deleting `ShippingCalculator` and all `Calculator::Shipping::*` classes in favor of a `pricing_type` enum plus `preferred_amount` columns on DeliveryMethod. That is reversed — see "Why calculators stay" below.
+## Implementation status (2026-08-06)
+
+**Phases 1–4 are implemented.** Phase 1 (`store_id`) shipped with the fulfillment rework; Phases 2–4 landed together:
+
+- **Provider interface**: `DeliveryRateProvider::Base` (`estimate` required; `book`/`release` no-ops; `integration_class` + `available_for_store?` class hooks; `integration` resolved from the method's store) and `DeliveryRateProvider::Internal`, which delegates to the method's calculator so nothing changes by default.
+- **`Estimate` value object** — `ActiveModel::Model` + `Attributes`, **not a `Struct`** as the design sketch below shows: CLAUDE.md forbids `Struct` for domain value objects. Fields as specified.
+- **Registry**: `Spree.delivery_rate_providers` (engine-seeded, initializer-extensible) with inclusion validation on `DeliveryMethod#rate_provider` on change only, blank allowed — so rows survive a provider gem being uninstalled.
+- **Model**: `rate_provider` string column, `DeliveryMethod::DEFAULT_RATE_PROVIDER`, `#rate_provider_instance` / `#rate_provider_class`.
+- **Estimator**: the single dispatch point now calls `rate_provider_instance.estimate(package)`; all filtering, VAT gross-up, tax resolution and sorting are untouched.
+- **Enriched `DeliveryRate`**: `carrier`, `service_level`, `estimated_delivery_date` and a single `metadata` JSON column (plain `serialize`, **not** the `Spree::Metadata` concern — that concern requires the legacy `public_metadata`/`private_metadata` pair, which the house rule forbids on new columns). Store serializer exposes carrier/service level/date; `metadata` is admin-only.
+- **Admin surface**: `GET /admin/delivery_methods/rate_providers` (filtered by `available_for_store?`, returns the default), `rate_provider` permitted + serialized, `adminClient.deliveryMethods.rateProviders()`, and a dashboard provider select that renders only when more than one provider is available — so it stays hidden until a carrier gem is installed. i18n in all six locales.
+
+**Acceptance criterion met:** the full core suite (7,463 examples) and API suite (2,661 examples) pass with zero failures and no spec modified to accommodate the change — the Internal provider's calculator delegation is behavior-identical.
+
+**Two deviations from the design below:** (1) `Internal#estimate` does **not** compute `estimated_delivery_date`. The sketch calls `days.business_days.from_now`, but core has no business-day arithmetic (no `business_time` gem, and the transit columns are only ever rendered as a range string). Turning business days into a date needs a per-market holiday calendar; guessing one would show customers a wrong date — carrier providers return the real date. (2) `Estimate` has **no `estimated_transit_days`** field: no `spree_delivery_rates` column persists it, so a value there would be silently discarded — worse than not offering it. The method's own `estimated_transit_business_days_min`/`_max` remain readable from any rate via `delivery_method`; a transit-days field can return together with a column when a carrier gem needs it. Additionally, `available_for_store?` is derived from `integration_class` on the base class (declaring the integration is all a carrier provider needs), and `DeliveryMethod` validates provider availability on save — the admin picker filter is display-only over the same rule.
+
## Problem
1. **Calculators can't call external APIs.** `ShippingCalculator#compute_package(package) → BigDecimal` is a synchronous, stateless computation with no credentials, no error handling, and no caching.
@@ -128,8 +144,10 @@ shared.** "UPS (Europe)" and "UPS (North America)" as separate
entity will be added. See decisions.md 2026-07-29.
The same decision commits the monorepo to **one reference
-`DeliveryRateProvider` backed by a multi-carrier aggregator** (Shippo or
-EasyPost — see Open Questions), mirroring Stripe as the reference gateway.
+`DeliveryRateProvider` backed by a multi-carrier aggregator** — settled
+as **EasyPost** (decisions.md 2026-08-06 reversal entry: BYOCA fit for
+Spree's larger-merchant profile + the only actively maintained official
+Ruby SDK) — mirroring Stripe as the reference gateway.
It is the first real consumer of this plan's interface and the default
answer for installs that want live carrier rates without per-carrier
method sprawl; the `Internal` calculator path stays for manual rates.
@@ -252,15 +270,19 @@ module Spree
# Structured result. `cost` is pre-tax and pre-VAT-gross-up; the Estimator
# applies gross_amount and tax rate resolution, same as it does for
# calculator output today.
- DeliveryRateEstimate = Struct.new(
- :cost,
- :carrier,
- :service_level,
- :estimated_delivery_date,
- :estimated_transit_days,
- :metadata,
- keyword_init: true
- )
+ # Shipped as Spree::DeliveryRateProvider::Estimate — an ActiveModel value
+ # object, not the Struct this sketch originally showed (CLAUDE.md: never
+ # use Struct for domain value objects).
+ class Estimate
+ include ActiveModel::Model
+ include ActiveModel::Attributes
+
+ attribute :cost, :decimal
+ attribute :carrier, :string
+ attribute :service_level, :string
+ attribute :estimated_delivery_date, :date
+ attribute :metadata, default: -> { {} }
+ end
class Base
attr_reader :delivery_method
@@ -433,7 +455,7 @@ The Store API already speaks this vocabulary: `Spree::Api::V3::DeliveryRateSeria
## Migration Path
-### Phase 1 — store ownership (independent, ship first)
+### Phase 1 — store ownership (independent, ship first) ✅ shipped
- Migration: `add_reference :spree_shipping_methods, :store, null: true, if_not_exists: true`, following `20260628000001_add_store_id_to_spree_promotions.rb`.
- `ShippingMethod` includes `SingleStoreResource`, declares `belongs_to :store`.
@@ -441,20 +463,20 @@ The Store API already speaks this vocabulary: `Spree::Api::V3::DeliveryRateSeria
- Update `shipping_method_factory.rb` and the admin controller (`shipping_methods_controller.rb`) to set/scope by store.
- `null: false` is deferred to the 6.0 cleanup, after the vendor interaction is settled.
-### Phase 2 — provider interface + Internal provider
+### Phase 2 — provider interface + Internal provider ✅ shipped
- Add `Base`, `Internal`, `DeliveryRateEstimate`, and `Spree::Current.provider_cache`.
- Add the `rate_provider` string column to `spree_shipping_methods` (nullable; blank means Internal).
- Wire the dispatch in `Estimator#calculate_shipping_rates`.
- **Zero behavior change is the acceptance criterion**: the full existing shipping suite passes untouched. Because Internal delegates to `calculator.compute` and all filtering/VAT/tax/sort logic is unchanged, any diff in rates is a bug.
-### Phase 3 — enrich ShippingRate
+### Phase 3 — enrich ShippingRate ✅ shipped
- Add `carrier`, `service_level`, `estimated_delivery_date` columns + the `Metadata` concern.
- Populate from `DeliveryRateEstimate` in the Estimator.
- Expose in the Store and Admin serializers; regenerate types via the pipeline in CLAUDE.md.
-### Phase 4 — admin surface (React dashboard only — no Rails admin in 6.0)
+### Phase 4 — admin surface (React dashboard only — no Rails admin in 6.0) ✅ shipped
- Admin API v3: `rate_provider` on the delivery-method serializer/permitted params, plus a provider-discovery endpoint (available providers filtered by `available_for_store?(store)`); admin-sdk resource + generated types.
- Dashboard delivery-method page: provider select + schema-driven calculator preference forms (`PreferencesForm`, per the 2026-07-21 routing-rules pattern), `<Can>`-gated, i18n in all locale files.
@@ -462,7 +484,7 @@ The Store API already speaks this vocabulary: `Spree::Api::V3::DeliveryRateSeria
### Phase 5 — reference external provider
-- Ship an EasyPost provider gem and a how-to guide, mirroring the custom-search-provider doc.
+- Ship an EasyPost provider gem (decisions.md 2026-08-06, reversal entry) and a how-to guide, mirroring the custom-search-provider doc — built on the official `easypost` gem. The EasyPost snippets elsewhere in this document are now the pick, not just illustration.
## Constraints on Current Work
@@ -482,13 +504,7 @@ The Store API already speaks this vocabulary: `Spree::Api::V3::DeliveryRateSeria
3. **Rate validation at completion.** Rates can expire between checkout and payment. Add `validate_rate(delivery_rate)` to the base class, or re-estimate and compare at completion? Leaning toward a lifecycle hook alongside `book`/`release`.
-4. **Aggregator pick for the reference provider.** Shippo vs EasyPost for
- the monorepo reference implementation (decisions.md 2026-07-29): EasyPost
- has the `spree_easypost` lineage; Shippo has the simpler API surface and
- pricing. Decide before Phase 2 implementation starts; the interface is
- aggregator-agnostic either way.
-
-5. **Backfill heuristic for multi-store installs.** The zone-overlap signal in Phase 1 is imperfect where several stores share a zone. Is loud logging plus manual reassignment sufficient, or should the task refuse to guess and require an explicit mapping?
+4. **Backfill heuristic for multi-store installs.** The zone-overlap signal in Phase 1 is imperfect where several stores share a zone. Is loud logging plus manual reassignment sufficient, or should the task refuse to guess and require an explicit mapping?
## Relationship to Other 6.0 Plans
diff --git a/docs/plans/6.0-fulfillment-and-delivery.md b/docs/plans/6.0-fulfillment-and-delivery.md
index e00be941e2..cde92d7c8f 100644
--- a/docs/plans/6.0-fulfillment-and-delivery.md
+++ b/docs/plans/6.0-fulfillment-and-delivery.md
@@ -4,7 +4,7 @@
**Target:** Spree 6.0
**Depends on:** `6.0-product-types.md` (`fulfillment_types` addendum 2026-07-27 — ProductType replaces ShippingCategory; **shipped**, including the `fulfillment_types` column), `6.0-cart-order-split.md` (where fulfillments/rates live pre-completion), `6.0-order-routing.md` (packages come from `for_allocation`), `6.0-normalize-state-to-status.md`. Coordinates with: `6.0-delivery-rate-provider.md` (owns `store_id` on DeliveryMethod; calculators stay per decisions.md 2026-07-27), `5.5-6.0-display-on-to-boolean.md` (`storefront_visible` — DeliveryMethod moved off the `Spree::DisplayOn` concern 2026-08-05), `6.0-multi-vendor-marketplace.md` (`vendor_id`, lifecycle events, `delivery_amount`). Gates: `6.0-6.1-split-adjustments.md` and `6.0-typed-stock-movements.md` are born with `fulfillment_id` — **this plan's Phase 1 must land before both**.
**Author:** Damian + Claude
-**Last updated:** 2026-08-06
+**Last updated:** 2026-08-06 (pickup work beyond shipped code deferred to 6.1; interface marked experimental — see Implementation status)
## Summary
@@ -36,6 +36,14 @@ Three changes in one:
- **`Order#line_items_without_delivery_rates` was memoized across a destroy.** `ensure_available_delivery_rates` calls `fulfillments.destroy_all` and then re-reads the list, so the cached value described fulfillments that no longer existed. Memoization removed, and the list is captured before the destroy so the error message keeps its product names.
- **`Fulfillment#refresh_rates` could leave nothing selected.** When the previously chosen method dropped out of the new quote (audience change, eligibility rule, zone edit), `selected_rate` came back nil and the fulfillment lost its selection. It now falls back to the estimator's own pick.
+**Pickup work beyond what has shipped is deferred to 6.1 (2026-08-06 — 6.0 is packed).** Everything already in code stays in 6.0 unchanged: the pickup/pickup_point fulfillment types and providers, `PickupPointProvider::Base` + `PickupPointOption`, the store discovery endpoints, `DeliveryMethodStockLocation`, and the full checkout selection flow (point chosen at the delivery step via `pickup_point_external_id`, server-validated, frozen into `pickup_point_data`). Deferred to 6.1 as one unit:
+
+- **Contract hardening**: (1) `PickupPointProvider` subclasses constructed with `new(delivery_method)` instead of `new` — today `DeliveryMethod#pickup_point_provider_instance` passes no arguments, leaving providers no path to `delivery_method.store.integrations` for credentials (same constructor shape as `DeliveryRateProvider::Base`); (2) `find_nearby` accepts optional `zipcode:`/`query:` alongside `latitude:`/`longitude:` — postcode/city search is the standard EU checkout pattern. Map-widget storefronts (InPost Geowidget) are unaffected either way — they skip `find_nearby` and only use the server-side `find_by_external_id` validation.
+- **Reference network provider**: none in 6.0 or promised for 6.1 core — community/later, plus a how-to guide written when the contract is hardened.
+- **Not selectable in 6.0**: `pickup_point` is removed from the dashboard `FULFILLMENT_TYPES` const (schema enum + select options) **and** from the `Spree.fulfillment_types` registry in `engine.rb` — so the type-select never offers it and the model's inclusion validation rejects setting it. Existing rows carrying the token stay loadable (validation runs on change only) and the pickup_points/selection endpoints still serve them. All other backend code, columns, endpoints and translations stay as shipped. Re-registering the token in 6.1 re-enables the whole surface.
+
+**Mitigation for deferring a signature change on a public class:** the pickup point provider interface is **not documented in 6.0 at all** — the v6 developer docs cover only the delivery rate provider interface. A class-level comment on `PickupPointProvider::Base` notes the constructor and `find_nearby` signature change in 6.1. With no docs inviting third-party providers, the 6.1 change breaks no sanctioned contract. Accepted trade-off for keeping 6.0 scope down; do not add pickup-provider docs or guides in any 6.0 work.
+
**Remaining for 6.0:** only the vendor axis (`belongs_to :vendor` replacing the `Spree::VendorConcern` decorator seam, `DeliveryMethodStockLocation` vendor-consistency validation, and refusing `pickup_stock_policy: 'any'` on vendor-owned locations). It is gated on `6.0-multi-vendor-marketplace.md` shipping the `vendor_id` column in its schema wave. Everything else outstanding is Phase 6 (6.1) cleanup.
### Shipped earlier (verified 2026-07-27, HEAD 4e5b6fd)
@@ -96,7 +104,7 @@ Replacement semantics:
### Fulfillment types are a strict registered set (revised 2026-08-02; supersedes "open strings, no inclusion validation")
-`shipping`, `pickup` (merchant location), `pickup_point` (third-party point — InPost locker, DHL ServicePoint), `digital`, `local_delivery` built in; extensible via `Spree.fulfillment_types << 'same_day_courier'` in an initializer. NOT a model — a type is a behavior discriminator only meaningful to code (splitter, estimator, provider); AR-record reference data was the countries/states mistake. But not open strings either: an unregistered/typo'd type silently produces empty intersections (no error, just missing rates), so `DeliveryMethod#fulfillment_type` and each element of `ProductType#fulfillment_types` validate inclusion against the registry — **on attribute change only**, so rows carrying tokens not yet registered (e.g. freshly migrated) stay loadable and savable. The registry is exposed to admin UIs via `GET /admin/delivery_methods/fulfillment_providers` (`fulfillment_types` key) — the dashboard renders type selects/checkboxes from it, so extension-registered types appear without dashboard changes (the JS `FULFILLMENT_TYPES` const is pre-fetch fallback + labels only).
+`shipping`, `pickup` (merchant location), `digital` built in for 6.0; extensible via `Spree.fulfillment_types << 'same_day_courier'` in an initializer. `pickup_point` (third-party point — InPost locker, DHL ServicePoint) is deferred to 6.1 (2026-08-06, see Implementation status). `local_delivery` was **cut from the built-in set entirely** (2026-08-06): by this plan's own modality-vs-segment test it is not a modality — same address requirement, zone mechanism, provider and lifecycle as `shipping`; "local delivery to postcodes X–Y" is a `shipping` method with a postal-code DeliveryZone. It returns only if it ever grows real provider behavior (delivery windows, courier assignment), registered together with that provider. NOT a model — a type is a behavior discriminator only meaningful to code (splitter, estimator, provider); AR-record reference data was the countries/states mistake. But not open strings either: an unregistered/typo'd type silently produces empty intersections (no error, just missing rates), so `DeliveryMethod#fulfillment_type` and each element of `ProductType#fulfillment_types` validate inclusion against the registry — **on attribute change only**, so rows carrying tokens not yet registered (e.g. freshly migrated) stay loadable and savable. The registry is exposed to admin UIs via `GET /admin/delivery_methods/fulfillment_providers` (`fulfillment_types` key) — the dashboard renders type selects/checkboxes from it, so extension-registered types appear without dashboard changes (the JS `FULFILLMENT_TYPES` const is pre-fetch fallback + labels only).
**Modality vs segment.** New fulfillment types are for genuinely new delivery *modalities* (need provider code anyway — the initializer is the smallest part of the work). Product *segments* ("oversized", "fragile") should NOT become custom types: model them with `DeliveryMethodRule` (weight/item-total/excluded-products — merchant-manageable in the dashboard, registry `Spree.delivery_method_rules` for custom rules; the former `Product#excluded_delivery_method_ids` column is gone per the 2026-08-06 decision — one-off subtractions are `ExcludedProductsRule`). The Wave 7 shipping→delivery data migration MAY mint custom tokens for 5.x shipping categories whose method bindings actually narrow (a category not served by all methods) — flattening those to `'shipping'` would silently widen eligibility — but that token-minting is a compatibility measure, not recommended modeling; the migration task must print the `Spree.fulfillment_types += [...]` initializer line for every token it mints.
@@ -265,7 +273,7 @@ end
### Store API flows (pickup)
-Merchant pickup: `GET /delivery_methods?fulfillment_type=pickup` → `GET /delivery_methods/:id/pickup_locations` (pickup-enabled StockLocations with package-scoped stock) → select with `stock_location_id`, which writes `Order#preferred_stock_location_id` (routing rule picks it up). Third-party points: `GET /delivery_methods/:id/pickup_points?latitude=&longitude=` (calls the method's `PickupPointProvider#find_nearby`; ephemeral value objects, never persisted) → select with `pickup_point_external_id` → validated via `find_by_external_id`, frozen into `fulfillment.pickup_point_data`. `PickupPointProvider::Base` + `PickupPointOption` struct as previously designed.
+Merchant pickup: `GET /delivery_methods?fulfillment_type=pickup` → `GET /delivery_methods/:id/pickup_locations` (pickup-enabled StockLocations with package-scoped stock) → select with `stock_location_id`, which writes `Order#preferred_stock_location_id` (routing rule picks it up). Third-party points: `GET /delivery_methods/:id/pickup_points?latitude=&longitude=` (`?zipcode=`/`?query=` arrive with the 6.1 contract hardening; calls the method's `PickupPointProvider#find_nearby`; ephemeral value objects, never persisted) → select with `pickup_point_external_id` → validated via `find_by_external_id`, frozen into `fulfillment.pickup_point_data`. `PickupPointProvider::Base` + `PickupPointOption` struct as previously designed.
## Migration Path
@@ -322,8 +330,9 @@ Batched, idempotent, resumable — same guarantees as the split-adjustments migr
- Dashboard (8 files still on `shipment` vocabulary) + CSV import/export contract + user docs. The legacy Rails admin's 26 shipping files are **deleted with `spree/admin` at 6.0**, not renamed — admin fulfillment management lives in the dashboard via Admin API/SDK.
- **CSV resolved 2026-08-05: `product_type` is required immediately, no mapping and no deprecation window.** This supersedes the earlier "importers get a mapping + deprecation window" intent — a compatibility mapping would translate onto a model that no longer decides anything (see the CSV note above). `shipping_category` is gone from both import and export.
-### Phase 6 — cleanup (6.1)
+### Phase 6 — cleanup + deferred pickup work (6.1)
+- **Pickup point contract hardening** (deferred 2026-08-06): `PickupPointProvider` constructor → `new(delivery_method)`, `find_nearby` gains `zipcode:`/`query:`, store `pickup_points` endpoint passes them through; drop the experimental marker and publish the custom-pickup-point-provider how-to guide.
- Drop deprecation aliases, `spree_shipping_categories` + `spree_shipping_method_categories`, `products.shipping_category_id`, dual-emitted `shipment.*` events, the dangling `admin_shipping_category_serializer` / v2 platform registrations.
- Also added by the 2026-08-05 work: `DeliveryMethod#display_on` / `#display_on=` / `#available_to_display?`, the `DISPLAY_ON_FRONT_END`/`BACK_END` constants and the `DeliveryMethod.normalize_audience` shim that accepts them, the `deprecated: true` `shipping_method_categories` / `shipping_categories` associations on DeliveryMethod, the `deprecated: true` `shipping_category` / `shipping_methods` associations on Product, `Variant#shipping_category` / `#shipping_category_id`, and the `spree_delivery_methods.display_on` column. Plus the method bridges listed above: `Estimator#shipping_rates`/`#shipping_methods`, `Package#shipping_rates`/`#to_shipment`, `Coordinator#shipments`, `Order#line_items_without_shipping_rates`, `Order#refresh_shipment_rates`, and `LineItem#shipping_cost`/`#display_shipping_cost`. The CSV surface needs no cleanup — it was cut outright in 6.0.
- `FulfillmentSerializer#fulfillment_type` can drop its computed fallback once every install has run `spree:migrate_shipping_to_delivery`.
diff --git a/docs/plans/6.0-integrations-admin.md b/docs/plans/6.0-integrations-admin.md
new file mode 100644
index 0000000000..9b9b0afc83
--- /dev/null
+++ b/docs/plans/6.0-integrations-admin.md
@@ -0,0 +1,91 @@
+# Integrations Admin
+
+**Status:** Design Finalized (open questions resolved interactively 2026-08-06)
+**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
+
+## 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::Integration` subclass holding credentials in model preferences, plus one or more stateless provider classes that resolve it via `store.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 on `MEILISEARCH_URL` env 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 as `Spree.fulfillment_providers` / `Spree.delivery_method_rules`. No descendants-scanning — eager-loading-dependent magic hides intent. `Spree::Integration` validates `type` inclusion against the registry on attribute change.
+- **Preference schema drives the UI.** `Spree::Integration` includes the existing `Spree::PreferenceSchema` concern. The types-discovery endpoint serves `serialized_preference_schema`; the dashboard renders forms with the existing `PreferencesForm` component. Secrets use `:password`-typed preferences and flow through the existing `Spree::Preferences::Masking` machinery — 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 `5.7-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_integrations` scopes; JWT access by CanCanCan on `Spree::Integration`.
+- **Verify before activate** (resolved 2026-08-06). Saving credentials never runs a network call — partial setups save fine, inactive. Flipping `active: true` runs `can_connect?` and rejects with 422 (`connection_error_message` in the error) on failure. Accepted trade-off: a vendor outage temporarily blocks *going live* (not editing); the explicit `POST /:id/test` endpoint remains for diagnostics at any time.
+- **Connection status is ephemeral** (resolved 2026-08-06). No `last_checked_at`/`last_error` columns — 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`)
+
+```ruby
+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 over `Rails.application.config.spree.integrations` (default `[]`).
+- `integration_group`, `integration_name`, `integration_key`, `icon_path` already 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 via `Spree.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**: `PreferencesForm` rendered from `preference_schema`, active toggle, "Test connection" button calling the test endpoint and surfacing `error_message` inline, destructive-confirmed disconnect.
+- `adminClient.integrations` resource 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
+
+1. Core: registry + `PreferenceSchema` include + type-inclusion validation + unique index migration.
+2. Admin API: controller, serializer, scopes, integration specs (happy path) + controller specs (masking round-trip, cross-store 404, unregistered type rejection).
+3. SDK resource + generated types.
+4. Dashboard gallery + sheet + settings-nav entry + i18n.
+5. 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 `constantize` a 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`, `5.7-payment-method-rules.md` (multi-account deferral), decisions.md 2026-07-30 (reference providers), 2026-08-06 (EasyPost)
diff --git a/docs/plans/6.0-product-types.md b/docs/plans/6.0-product-types.md
index 810f45dc91..d46952f6e3 100644
--- a/docs/plans/6.0-product-types.md
+++ b/docs/plans/6.0-product-types.md
@@ -265,7 +265,7 @@ ProductType editing:
`ShippingCategory` is dropped in 6.0 (`6.0-fulfillment-and-delivery.md`); its only real job — "which delivery methods may serve this product?" — moves here:
-- `fulfillment_types` JSON column on `spree_product_types` (**created in this plan's Phase 1**, jsonb-guarded, nullable — the `['shipping']` default is model-level), e.g. `["shipping"]`, `["digital"]`, `["shipping", "pickup", "local_delivery"]`.
+- `fulfillment_types` JSON column on `spree_product_types` (**created in this plan's Phase 1**, jsonb-guarded, nullable — the `['shipping']` default is model-level), e.g. `["shipping"]`, `["digital"]`, `["shipping", "pickup"]` (6.0 built-in tokens: shipping/pickup/digital — decisions.md 2026-08-06).
- **Products without a ProductType default to `['shipping']`** — the reconciliation between optional ProductType and today's effectively-mandatory ShippingCategory (every product presence-validates one, with auto-assignment).
- The fulfillment plan's data migration creates/assigns types **only where the category carried signal** — products in a digital shipping category get a `Digital` ProductType (`fulfillment_types: ['digital']`). This is the sanctioned one-time initial assignment.
- `Product#digital?` re-implements on top of this (today it's a four-hop chain through ShippingCategory → shipping-method scope → calculator class). `Product#fulfillment_types` is **net-new** surface — no such method exists today.
diff --git a/docs/plans/decisions.md b/docs/plans/decisions.md
index 71833a49c9..399833affc 100644
--- a/docs/plans/decisions.md
+++ b/docs/plans/decisions.md
@@ -239,6 +239,101 @@ when there is a real implementation behind it, never a speculative column
plus a provider key nobody declares.
+## 2026-08-06: Integrations become the admin-managed credential surface; verify-before-activate
+
+`Spree::Integration` (shipped 5.x, previously zero subclasses, no API,
+no UI) becomes the single credential home for every provider seam —
+delivery rates, tax, fulfillment, pickup point networks. New plan:
+`6.0-integrations-admin.md`. Explicit `Spree.integrations` registry
+(house pattern, no descendants-scanning); Admin API v3 CRUD + types
+discovery reusing the `PreferenceSchema`/`Masking` machinery from
+payment methods (secrets are `:password`-typed preferences, masked on
+read, round-trip-guarded on write); dashboard `/settings/integrations`
+gallery grouped by `integration_group` — the one page showing what is
+connected to the current store. Semantics settled interactively:
+**verify before activate** (saving credentials never makes a network
+call; flipping `active: true` runs `can_connect?` and 422s on failure;
+`POST /:id/test` for diagnostics) and **ephemeral connection status**
+(no `last_checked_at`/`last_error` columns). Constraints now: new
+provider gems ship an Integration subclass — no env-var credential
+contracts for per-store providers; no per-provider credential UIs —
+provider pickers deep-link to the integrations page.
+
+## 2026-08-06: Pickup point provider contract hardened; no reference network gem in 6.0
+
+Decided before any concrete `PickupPointProvider` exists, precisely
+because none does: (1) providers are constructed with
+`new(delivery_method)` — the current zero-arg construction leaves no
+path to `store.integrations` for credentials; (2) `find_nearby` accepts
+`zipcode:`/`query:` alongside `latitude:`/`longitude:` (postcode/city
+search is the standard EU checkout pattern; map-widget storefronts skip
+`find_nearby` and only use server-side `find_by_external_id`
+validation). Both are free now and breaking later. **No reference
+network provider (InPost/Sendcloud) ships in 6.0** — community/later,
+with a how-to guide. The checkout flow itself is confirmed as
+shipped: point selected during checkout at the delivery step
+(`pickup_point_external_id` on rate selection, server-validated, frozen
+into `fulfillment.pickup_point_data`).
+
+**Amended 2026-08-06 (same day, Damian):** all pickup work beyond
+already-shipped code — including the contract hardening above — is
+**deferred to 6.1**; 6.0 is packed. The pickup point provider
+interface is **not documented in 6.0 at all** — the v6 developer docs
+cover only the delivery rate provider interface; a class-level comment
+on `PickupPointProvider::Base` notes the constructor and `find_nearby`
+signature change in 6.1, so the change breaks no sanctioned contract.
+Accepted trade-off, recorded in `6.0-fulfillment-and-delivery.md`
+(Implementation status + Phase 6). Constraint: no 6.0 doc or guide may
+cover the pickup point provider interface.
+
+**Second amendment 2026-08-06 (Damian):** `pickup_point` is also
+removed from the `Spree.fulfillment_types` registry and the dashboard
+`FULFILLMENT_TYPES` const — not selectable anywhere in 6.0; existing
+rows stay loadable (inclusion validates on change only) and the shipped
+endpoints still serve them; one-word re-registration in 6.1 restores
+the surface. `local_delivery` is removed the same way, but as a **cut,
+not a deferral**: it fails the plan's own modality-vs-segment test —
+identical address/zone/provider/lifecycle semantics to `shipping`; the
+local-delivery use case is a `shipping` method with a postal-code
+DeliveryZone. It returns only alongside real provider behavior
+(delivery windows, courier assignment). 6.0 built-in types:
+`shipping`, `pickup`, `digital`.
+
+## 2026-08-06: EasyPost is the reference delivery rate provider (Shippo pick reversed same day)
+
+Resolves the EasyPost-or-Shippo pick left open on 2026-07-29/30. The
+monorepo's reference `DeliveryRateProvider` (`6.0-delivery-rate-provider.md`
+Phase 5) is built on **Shippo**. Competitor survey: no platform ships
+direct per-carrier integrations in core — Shopify and WooCommerce built
+their in-house label services on an aggregator (both historically
+EasyPost-backed), BigCommerce leans on ShipperHQ, and the OSS field
+(Medusa, Saleor, Vendure) ships a provider interface with aggregator
+plugins, Medusa's ecosystem having standardized on Shippo. A direct
+UPS/USPS/FedEx trio was rejected: three churning carrier APIs to
+maintain, US-only coverage against Spree's heavily European base, and
+worse merchant onboarding than one aggregator account. Between the two
+aggregators, Shippo fits the reference provider's audience (default OSS
+install, SMB merchant): simpler API surface, pay-as-you-go pricing with
+no monthly fee, solid EU carrier set. The `spree_easypost` lineage
+carries no weight — it targets the pre-6.0 architecture and would be a
+rewrite regardless. The interface stays aggregator-agnostic; EasyPost,
+Sendcloud (EU-first, strong service-point coverage) or direct-carrier
+providers remain buildable as third-party gems on the same base class.
+
+**Reversed 2026-08-06 (same day, Damian): EasyPost.** Two factors the
+Shippo lean under-weighted: (1) **Spree's merchant profile skews
+larger** — merchants with negotiated UPS/FedEx contracts who want to
+connect their own carrier accounts, which is EasyPost's core BYOCA
+(bring-your-own-carrier-account) model, not Shippo's SMB
+default-account posture; (2) **Ruby SDK reality**: EasyPost maintains
+its official `easypost` gem (7.6.0, Feb 2026), while Shippo's official
+Ruby client last released in April 2020 and signals deprecation — for
+a Ruby-first reference implementation that difference is decisive (the
+Shippo path would mean hand-rolling and maintaining an HTTP client in
+the provider gem). Everything else in the original entry stands:
+aggregator over direct-carrier trio, aggregator-agnostic interface,
+third-party gems welcome on the same base class.
+
## 2026-08-05: Dashboard form values must not embed SDK entity types
The returns rework regenerated the admin SDK types, and the new `Order`
@@ -362,7 +457,6 @@ dashboard pages. Reviewing what remains settled four things:
name for historical reference until 6.1). `Spree::Metafields` lands on
the three entities on the same branch.
-
## 2026-08-05: v5 developer docs are frozen until the 6.0 release; 6.0 docs land under docs/v6
The pages under `docs/developer/` document the stable 5.x line and stay
diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/settings/delivery-methods.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/settings/delivery-methods.tsx
index 073c27df7b..c76a10cda4 100644
--- a/packages/dashboard/src/routes/_authenticated/$storeId/settings/delivery-methods.tsx
+++ b/packages/dashboard/src/routes/_authenticated/$storeId/settings/delivery-methods.tsx
@@ -672,7 +672,7 @@ function DeliveryMethodFormFields({ form }: { form: UseFormReturn<DeliveryMethod
</Field>
)}
- {(fulfillmentType === 'shipping' || fulfillmentType === 'pickup_point') && (
+ {fulfillmentType === 'shipping' && (
<>
<Field>
<FieldLabel>{t('admin.fields.delivery_method.calculator.label')}</FieldLabel>
diff --git a/packages/dashboard/src/schemas/delivery-method.ts b/packages/dashboard/src/schemas/delivery-method.ts
index 128c8d321d..1a0750a97d 100644
--- a/packages/dashboard/src/schemas/delivery-method.ts
+++ b/packages/dashboard/src/schemas/delivery-method.ts
@@ -1,6 +1,6 @@
import { z } from 'zod/v4'
-export const FULFILLMENT_TYPES = ['shipping', 'digital', 'pickup', 'pickup_point'] as const
+export const FULFILLMENT_TYPES = ['shipping', 'digital', 'pickup'] as const
/**
* One eligibility rule as held in form state. `id` is absent for rules added
diff --git a/spree/api/spec/controllers/spree/api/v3/store/delivery_methods_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/store/delivery_methods_controller_spec.rb
index c2a70164f9..f89a254372 100644
--- a/spree/api/spec/controllers/spree/api/v3/store/delivery_methods_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/store/delivery_methods_controller_spec.rb
@@ -152,7 +152,10 @@ RSpec.describe Spree::Api::V3::Store::DeliveryMethodsController, type: :controll
end
end
stub_const('TestPickupPointProvider', test_provider)
- pickup_method.update!(fulfillment_type: 'pickup_point', pickup_point_provider: 'TestPickupPointProvider')
+ # update_columns: 'pickup_point' is deferred to 6.1 and no longer a
+ # registered fulfillment type, but the endpoint still serves rows
+ # carrying it (created before the deferral or via an extension).
+ pickup_method.update_columns(fulfillment_type: 'pickup_point', pickup_point_provider: 'TestPickupPointProvider')
end
it 'returns nearby points' do
diff --git a/spree/api/spec/integration/spree/api/v3/admin/delivery_settings_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/delivery_settings_spec.rb
index 941e03f690..a1dd9123ba 100644
--- a/spree/api/spec/integration/spree/api/v3/admin/delivery_settings_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/admin/delivery_settings_spec.rb
@@ -36,7 +36,7 @@ RSpec.describe 'Admin Delivery Settings API', type: :request, swagger_doc: 'api-
consumes 'application/json'
produces 'application/json'
security [api_key: [], bearer_auth: []]
- description 'Creates a delivery method. fulfillment_type is one of shipping, digital, pickup, pickup_point.'
+ description 'Creates a delivery method. fulfillment_type is one of shipping, digital, pickup.'
admin_scope :write, :settings
admin_sdk_example 'delivery-methods/create'
@@ -49,7 +49,7 @@ RSpec.describe 'Admin Delivery Settings API', type: :request, swagger_doc: 'api-
name: { type: :string, example: 'Express' },
admin_name: { type: :string, nullable: true },
code: { type: :string, nullable: true },
- fulfillment_type: { type: :string, enum: %w[shipping digital pickup pickup_point], example: 'shipping' },
+ fulfillment_type: { type: :string, enum: %w[shipping digital pickup], example: 'shipping' },
storefront_visible: { type: :boolean, example: true },
tracking_url: { type: :string, nullable: true },
estimated_transit_business_days_min: { type: :integer, nullable: true },
diff --git a/spree/api/spec/integration/spree/api/v3/store/delivery_methods_spec.rb b/spree/api/spec/integration/spree/api/v3/store/delivery_methods_spec.rb
index a4bca6590b..4ea9f3061e 100644
--- a/spree/api/spec/integration/spree/api/v3/store/delivery_methods_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/store/delivery_methods_spec.rb
@@ -18,7 +18,7 @@ RSpec.describe 'Store Delivery Methods API', type: :request, swagger_doc: 'api-r
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: :fulfillment_type, in: :query, type: :string, required: false,
- description: 'Filter: shipping, digital, pickup, pickup_point'
+ description: 'Filter: shipping, digital, pickup'
response '200', 'delivery methods found' do
before do
diff --git a/spree/core/app/models/spree/pickup_point_provider/base.rb b/spree/core/app/models/spree/pickup_point_provider/base.rb
index 6eb06bbecc..6e677df0bc 100644
--- a/spree/core/app/models/spree/pickup_point_provider/base.rb
+++ b/spree/core/app/models/spree/pickup_point_provider/base.rb
@@ -4,6 +4,11 @@ module Spree
# ServicePoints, ...). Points are ephemeral value objects — never
# persisted; the selected point is validated via +find_by_external_id+
# and frozen into +fulfillment.pickup_point_data+.
+ #
+ # Not yet a stable extension point: in 6.1 the constructor becomes
+ # +new(delivery_method)+ (credential access via the method's store
+ # integrations) and +find_nearby+ gains +zipcode:+/+query:+ params.
+ # Build third-party providers against 6.1, not this shape.
class Base
# @return [Array<Spree::PickupPointOption>]
def find_nearby(latitude:, longitude:, limit: 20)
diff --git a/spree/core/lib/spree/core/engine.rb b/spree/core/lib/spree/core/engine.rb
index e13c8e3fd3..dd9eee13f3 100644
--- a/spree/core/lib/spree/core/engine.rb
+++ b/spree/core/lib/spree/core/engine.rb
@@ -188,7 +188,7 @@ module Spree
# Open strings, no inclusion validation — extensions append their own
# (e.g. 'same_day_courier').
- Rails.application.config.spree.fulfillment_types = %w[shipping pickup pickup_point digital local_delivery]
+ Rails.application.config.spree.fulfillment_types = %w[shipping pickup digital]
# Selectable order routing strategies. The internal Reducer collaborator
# is intentionally NOT listed — it is not a Strategy::Base. Plugins add
diff --git a/spree/core/spec/models/spree/delivery_method_spec.rb b/spree/core/spec/models/spree/delivery_method_spec.rb
index 27bd249ccd..290c066708 100644
--- a/spree/core/spec/models/spree/delivery_method_spec.rb
+++ b/spree/core/spec/models/spree/delivery_method_spec.rb
@@ -36,8 +36,7 @@ describe Spree::DeliveryMethod, type: :model do
it 'is decided by the fulfillment provider, not the fulfillment type' do
[
['digital', 'Spree::FulfillmentProvider::Digital'],
- ['pickup', 'Spree::FulfillmentProvider::Pickup'],
- ['pickup_point', 'Spree::FulfillmentProvider::PickupPoint']
+ ['pickup', 'Spree::FulfillmentProvider::Pickup']
].each do |fulfillment_type, provider|
method = create(:delivery_method, fulfillment_type: fulfillment_type, fulfillment_provider: provider)
diff --git a/spree/core/spec/models/spree/fulfillment_provider/base_spec.rb b/spree/core/spec/models/spree/fulfillment_provider/base_spec.rb
index de3eafa8a5..17da991886 100644
--- a/spree/core/spec/models/spree/fulfillment_provider/base_spec.rb
+++ b/spree/core/spec/models/spree/fulfillment_provider/base_spec.rb
@@ -25,7 +25,11 @@ describe Spree::FulfillmentProvider::Base, type: :model do
Spree::FulfillmentProvider::Pickup,
Spree::FulfillmentProvider::PickupPoint
)
- expect(Spree.fulfillment_types).to include('shipping', 'pickup', 'pickup_point', 'digital', 'local_delivery')
+ expect(Spree.fulfillment_types).to include('shipping', 'pickup', 'digital')
+ # Deferred to 6.1: pickup_point (provider ships, type unregistered) and
+ # local_delivery (no implementation — a shipping method with a
+ # postal-code zone covers the use case today).
+ expect(Spree.fulfillment_types).not_to include('pickup_point', 'local_delivery')
end
end