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_id field on ProductSerializer ✓
• expand=default_variant on ProductSerializer ✓

Remove now (5.4):

• Remove expand=master_variant from ProductSerializer
• Remove is_master field 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):

New fields added:

• fulfillment_type on ShipmentSerializer (returns 'shipping' or 'digital' based on current shipping method)
• fulfilled_at (alias for shipped_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:

# 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-split-adjustments.md

The model split (Adjustment → TaxLine, Discount, Fee) happens in 6.0. But the serialized totals can be renamed now for clarity:

Add new field:

• fee_total / display_fee_total on Cart/Order (returns 0 until 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 — removed expand=master_variant ✓
• admin/product_serializer.rb — removed expand=master_variant ✓
• variant_serializer.rb — removed is_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 — prefix ship → ful ✓
• core/app/models/spree/shipping_method.rb — prefix shpm → dm ✓
• core/app/models/spree/shipping_rate.rb — prefix shpr → dr ✓
• core/app/models/spree/inventory_unit.rb — prefix iu → 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)

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.

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_variant in 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