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.
Store API 5.4 Bridges for 6.0
Status: Implemented (PR #13782) Target: Spree 5.4 (next minor) Depends on: None — all changes are serializer/controller renames on existing models Author: Damian + Claude Last updated: 2026-03-17
Summary
Introduce 6.0 Store API naming NOW in 5.4, with breaking changes. No aliases, no deprecation periods — clean breaks. This gives storefront developers the final API shape before models are renamed in 6.0.
The approach: change the API surface (serializers, response keys, endpoint paths) in 5.4 while the models stay unchanged until 6.0. Serializers are the translation layer.
Scope
Only changes where the API field/endpoint name changes between 5.4 and 6.0. Purely additive features (new endpoints, new fields, new resources) ship with their 6.0 plan and don't need bridging.
Changes
1. Remove master_variant, use default_variant only
Plan: 6.0-remove-master-variant.md
Already done in current API:
default_variant_idfield on ProductSerializer ✓expand=default_varianton ProductSerializer ✓
Remove now (5.4):
- Remove
expand=master_variantfrom ProductSerializer - Remove
is_masterfield from VariantSerializer
# ProductSerializer — REMOVE:
one :master,
key: :master_variant,
resource: Spree.api.variant_serializer,
if: proc { expand?('master_variant') }
# VariantSerializer — REMOVE:
# is_master attribute (no longer exposed)
SDK: Remove StoreVariant.is_master from TypeScript types. Remove expand=master_variant from SDK methods.
2. Shipments → Fulfillments, Shipping → Delivery
Plan: 6.0-fulfillment-and-delivery.md
Rename in serializers (model stays Shipment until 6.0):
| Before (5.4) | After (5.4) | Serializer change |
|---|---|---|
shipments (nested in Cart/Order) |
fulfillments |
Change key: on association |
shipping_rates (nested in Shipment) |
delivery_rates |
Change key: on association |
shipping_method (nested in ShipmentSerializer) |
delivery_method |
Change key: on association |
ShipmentSerializer fields: state, tracking, shipped_at |
status, tracking, fulfilled_at |
Rename attributes |
ShippingMethodSerializer |
Rename to DeliveryMethodSerializer |
New file, delegates to same model |
ShippingRateSerializer |
Rename to DeliveryRateSerializer |
New file, delegates to same model |
shipment_state (on Order) |
fulfillment_status |
Rename attribute |
ship_total / display_ship_total (on Cart/Order) |
delivery_total / display_delivery_total |
Rename attributes |
New fields added:
fulfillment_typeon ShipmentSerializer (returns'shipping'or'digital'based on current shipping method)fulfilled_at(alias forshipped_at)
Endpoint renames:
# Before
GET/PATCH /api/v3/store/carts/:id/shipments
# After
GET/PATCH /api/v3/store/carts/:id/fulfillments
Rename controller file: Carts::ShipmentsController → Carts::FulfillmentsController.
# routes
namespace :carts do
resources :fulfillments, only: [:index, :update]
end
Cart/Order serializer changes:
# CartSerializer — rename keys
many :shipments, # model association unchanged
key: :fulfillments, # API key changes
resource: Spree.api.shipment_serializer # serializer handles field renames
# Rename money fields
attribute :delivery_total do |order|
order.shipment_total
end
attribute :display_delivery_total do |order|
Spree::Money.new(order.shipment_total, currency: order.currency).to_s
end
# Remove: ship_total, display_ship_total
SDK: Rename StoreShipment → StoreFulfillment, StoreShippingMethod → StoreDeliveryMethod, StoreShippingRate → StoreDeliveryRate. Update client.carts.shipments → client.carts.fulfillments.
3. State → Status everywhere
Plan: 6.0-normalize-state-to-status.md
Models still use state column until 6.0. Serializers translate:
| Serializer | Before (5.4) | After (5.4) |
|---|---|---|
| ShipmentSerializer | state |
status (reads object.state) |
| PaymentSerializer | state |
status (reads object.state) |
| GiftCardSerializer | state |
status (reads object.state) |
| OrderSerializer | shipment_state |
fulfillment_status (reads object.shipment_state) |
| OrderSerializer | payment_state |
payment_status (reads object.payment_state) |
# ShipmentSerializer (becoming FulfillmentSerializer in API)
attribute :status do |shipment|
shipment.state
end
# Remove: state attribute
# OrderSerializer
attribute :fulfillment_status do |order|
order.shipment_state
end
attribute :payment_status do |order|
order.payment_state
end
# Remove: shipment_state, payment_state attributes
SDK: Rename state → status on StoreFulfillment, StorePayment, StoreGiftCard. Rename shipment_state → fulfillment_status, payment_state → payment_status on StoreOrder.
4. Adjustment totals naming
Plan: 6.0-6.1-split-adjustments.md
The model split (Adjustment → TaxLine, Discount, Fee) happens in 6.0. But the serialized totals can be renamed now for clarity:
| Before (5.4) | After (5.4) | On |
|---|---|---|
adjustment_total |
adjustment_total |
Cart/Order — keep as-is (sum of all adjustments) |
ship_total / display_ship_total |
delivery_total / display_delivery_total |
Cart/Order (covered in #2 above) |
Add new field:
fee_total/display_fee_totalon Cart/Order (returns0until Fee model exists in 6.0)
adjustment_total stays — it's a genuine total across all adjustment types and renaming it would break every storefront's price breakdown display without adding clarity.
5. Classification → ProductCategory (naming only)
Plan: 6.0-replace-taxons-with-categories.md
The Store API already uses categories naming. No serializer changes needed. The Classification model rename is internal.
Implementation Status
All changes implemented in PR #13782. Versions bumped to 0.12.0 for both @spree/sdk and @spree/next.
Files created
api/app/serializers/spree/api/v3/fulfillment_serializer.rb✓api/app/serializers/spree/api/v3/delivery_method_serializer.rb✓api/app/serializers/spree/api/v3/delivery_rate_serializer.rb✓api/app/serializers/spree/api/v3/admin/fulfillment_serializer.rb✓api/app/serializers/spree/api/v3/admin/delivery_method_serializer.rb✓api/app/serializers/spree/api/v3/admin/delivery_rate_serializer.rb✓api/app/controllers/spree/api/v3/store/carts/fulfillments_controller.rb✓api/spec/controllers/spree/api/v3/store/carts/fulfillments_controller_spec.rb✓api/spec/integration/spree/api/v3/store/fulfillments_spec.rb✓
Files deleted
api/app/serializers/spree/api/v3/shipment_serializer.rb✓api/app/serializers/spree/api/v3/shipping_method_serializer.rb✓api/app/serializers/spree/api/v3/shipping_rate_serializer.rb✓api/app/serializers/spree/api/v3/admin/shipment_serializer.rb✓api/app/serializers/spree/api/v3/admin/shipping_method_serializer.rb✓api/app/serializers/spree/api/v3/admin/shipping_rate_serializer.rb✓api/app/controllers/spree/api/v3/store/carts/shipments_controller.rb✓api/spec/controllers/spree/api/v3/store/carts/shipments_controller_spec.rb✓api/spec/integration/spree/api/v3/store/shipments_spec.rb✓
Files modified
cart_serializer.rb—ship_total→delivery_total,shipments→fulfillments✓order_serializer.rb—shipment_state→fulfillment_status,payment_state→payment_status,ship_total→delivery_total,shipments→fulfillments✓admin/order_serializer.rb—shipments→fulfillments,user_id→customer_id,expand=user→expand=customer✓admin/address_serializer.rb—user_id→customer_id✓admin/store_credit_serializer.rb—user_id→customer_id✓admin/credit_card_serializer.rb—user_id→customer_id✓newsletter_subscriber_serializer.rb—user_id→customer_id✓product_serializer.rb— removedexpand=master_variant✓admin/product_serializer.rb— removedexpand=master_variant✓variant_serializer.rb— removedis_master✓payment_serializer.rb—state→status✓gift_card_serializer.rb—state→status✓routes.rb—/shipments→/fulfillments✓dependencies.rb— added new serializer registrations, pointed old keys to new classes ✓core/app/models/spree/shipment.rb— prefixship→ful✓core/app/models/spree/shipping_method.rb— prefixshpm→dm✓core/app/models/spree/shipping_rate.rb— prefixshpr→dr✓core/app/models/spree/inventory_unit.rb— prefixiu→fi✓
Auto-generated (regenerated)
packages/sdk/src/types/generated/— all TS types ✓packages/sdk/src/zod/generated/— all Zod schemas ✓packages/admin-sdk/src/types/generated/— all admin TS types ✓docs/api-reference/store.yaml— OpenAPI spec ✓
SDK/Next packages
packages/sdk/src/store-client.ts—shipments→fulfillments✓packages/sdk/src/types/index.ts— type re-exports updated ✓packages/sdk/tests/— tests + mocks updated ✓packages/next/src/actions/cart.ts—getShipments→getFulfillments,selectShippingRate→selectDeliveryRate✓packages/next/src/index.ts— re-exports updated ✓packages/next/tests/— tests updated ✓- Both packages bumped to 0.12.0 with changesets ✓
Docs updated
packages/sdk/README.md✓packages/next/README.md✓docs/developer/sdk/store/cart-checkout.mdx✓docs/developer/sdk/quickstart.mdx✓docs/developer/sdk/store/payments.mdx✓docs/developer/sdk/configuration.mdx✓docs/developer/storefront/nextjs/spree-next-package.mdx✓docs/developer/storefront/nextjs/quickstart.mdx✓
Test results
- Backend integration tests: 149/149 pass ✓
- SDK tests: 140/140 pass ✓
- Next.js tests: 71/71 pass ✓
- TypeScript typecheck: all packages pass ✓
- Admin controller/feature specs: pass ✓
What stays unchanged (bridges already done or not needed)
| Feature | Status |
|---|---|
images → media |
Done in 5.4 (PR #13778) ✓ |
taxons → categories |
Already using categories in API ✓ |
expand=default_variant |
Already exists ✓ |
default_variant_id on products |
Already exists ✓ |
| ProductType, Collections, Stock Reservations, Returns/Claims, Channels/Catalogs | Purely additive — ship with 6.0 |
Prefixed IDs — changed in 5.4
Prefixed IDs are updated to match the new vocabulary. The find_by_prefix_id! method ignores the prefix during decoding (it splits on _ and decodes only the Sqids portion), so old IDs with old prefixes still resolve correctly.
| Model | Old prefix | New prefix |
|---|---|---|
| Shipment | ship_ |
ful_ |
| ShippingMethod | shpm_ |
dm_ |
| ShippingRate | shpr_ |
dr_ |
| InventoryUnit | iu_ |
fi_ |
NOT changed in 5.4 (deferred to 6.0 model rename)
Event names
Event names (shipment.shipped, shipment.canceled) are not changed in 5.4. Webhook subscribers and event listeners depend on these strings. They change in 6.0 to fulfillment.fulfilled, fulfillment.canceled with old names emitted alongside for one release.
Constraints on Current Work
- All new Store API code must use the 5.4 naming. No
shipment,shipping_method,state,master_variantin new endpoints. - SDK examples and docs must use new naming after this ships.
- Admin API is not affected by this plan. Admin serializers may keep old naming until 6.0 model renames happen (or can be bridged separately).
References
- Prior art:
5.4-6.0-product-media-system.md(same bridge pattern: API naming changed in 5.4, model renamed in 6.0) - All 6.0 plans in
docs/plans/6.0-*.md - Store API inventory: 32 endpoint groups, 56 serializers