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 Naming Standardization
Status: Implemented — the 5.4 API + model aliases shipped, and the 6.0 column/table renames that a public surface actually exposed landed 2026-09-02 (spree/spree#14559). Two renames deferred to 6.1 by the leakage rule below: credit card cc_type/last_digits, and the order/cart address foreign keys.
Target: Spree 5.4 (API surface + model aliases ✓); Spree 6.0 (database columns/tables)
Depends on: 5.4-store-api-bridges.md (same pattern: rename API surface now, models/DB later)
Author: Damian + Claude
Last updated: 2026-09-02
Summary
Standardize Spree Store API entity and attribute names against industry conventions (Shopify, Medusa, Saleor, Vendure, BigCommerce, commercetools). Changes follow the established bridge pattern: rename serializers, controllers, and add model aliases now (5.4), defer database column/table renames to 6.0.
Key Decisions (do not deviate without discussion)
- All changes are breaking in the Store API — no backward compatibility, new names only (same approach as
5.4-store-api-bridges.md) - Models get alias accessors for new names pointing to old columns — serializers and services use the new names directly
- Database column/table renames are deferred to 6.0
- Controllers accept new param names only — no backward compat for old names
2026-09-02: the 6.0 column renames are scoped by public leakage, not by completeness
The 5.4 aliases already make every API response speak the new names, so a
column rename only earns its churn where the old name still reaches a public
surface. Three things bypass an alias: Ransack filter keys (the whitelist
publishes the column, not the alias), validation error keys (details.zipcode
comes back to a client that sent postal_code), and delegated method names
(bill_address_firstname, which the dashboard's order table sorts by).
Renamed in 6.0 — each leaks by at least two of those three:
spree_addresses.firstname/lastname/zipcode→first_name/last_name/postal_codespree_option_types.presentation/spree_option_values.presentation→label(plus the two Mobility translation tables)Spree::WishedItem→Spree::WishlistItem(class + table) — no v3 leak, but the class and table are the only ones that never matched the serializer the API already ships. Thewi_prefix stays: a prefixed ID is a Store API identifier clients hold, and this plan does not break the Store API without a reason a caller can seespree_line_items.promo_total→discount_total— no v3 leak either, but Order and LineItem currently alias in opposite directions, which is a reading trap worth closing while the rest of the family moves
Deferred, because no public surface exposes them and the alias is complete:
spree_credit_cards.cc_type/last_digits→brand/last4— absent from the v3 contract, not validated, aliases already cover read and writespree_orders/spree_cartsbill_address_id/ship_address_id→billing_address_id/shipping_address_id— the largest item by far (~1,000 references) and the weakest case: the FK is never serialized and checkout errors surface as the codeship_address_required, not a column key
Both stay on the 6.1 alias-removal list; they rename when something else forces that table open.
2026-09-02: legacy names keep working one release
Each rename leaves the old name readable until 6.1, matching what
Spree::Order already does for promo_total / item_count and what
Spree::StockItem = StockLevel does for the class rename. Three shapes, and
the differences matter:
alias_attribute(the address and total columns) — a full bridge: Rails resolves it insidewhereandfind_byas well as on an instance.- A plain deprecated method (
OptionType#presentation,OptionValue#presentation) — instance reads and writes only. Mobility ownslabel, so analias_attributeis impossible, andwhere(presentation:)names a column that no longer exists and raises. Readers must not infer query support from the other two. - A constant alias (
Spree::WishedItem,Spree::PresentationTranslatable) — a plain assignment that emits no warning, following the shipped 6.0 precedent. ADeprecatedConstantProxywould warn but failsis_a?/===, so legacy code branching on the constant would silently take the wrong path.
2026-09-03: the wishlist item prefix stays wi_
The first cut of this work moved the prefixed ID to wli_ alongside the class
and table, citing the si_ → sl_ precedent in
6.0-typed-stock-movements.md. That was wrong. A prefixed ID is a Store API
identifier a client holds — decode_own_prefixed_id rejects a foreign
prefix, so every wi_... a storefront had cached would 404 on
PATCH/DELETE /store/wishlists/:id/items/:item_id.
The precedent does not transfer: StockLevel is admin-side, so its prefix
change breaks no storefront. This plan's own rule is that a rename must be
earned by something a caller can see, and nothing about wi_ misleads a
caller — it is opaque. The class and table rename is what closes the gap with
the serializer; the prefix was churn with a customer-visible cost.
has_prefix_id :wi therefore stays on Spree::WishlistItem. A new model gets
a prefix that suits it; an existing one keeps the prefix it issued.
2026-09-02: no upgrade step for these renames
rename_column carries the rows, so there is nothing to backfill. The 5.6→6.0
manifest lists data backfills only; db:migrate is the whole upgrade path here.
Changes
1. Address: ship_address / bill_address → shipping_address / billing_address
Serializers: Cart and Order serializers use key: :billing_address / key: :shipping_address on the association.
Controllers: Cart update accepts shipping_address_id, billing_address_id, shipping_address: {}, billing_address: {}.
Service: Carts::Update uses assign_address(:shipping_address) / :billing_address directly.
Model aliases (already existed + new):
alias_method :billing_address, :bill_address(existed)alias_method :shipping_address, :ship_address(existed)alias_attribute :billing_address_id, :bill_address_id(new)alias_attribute :shipping_address_id, :ship_address_id(new)alias shipping_address_attributes= ship_address_attributes=(new)alias billing_address_attributes= bill_address_attributes=(new)
Database: deferred to 6.1. The foreign key is never serialized and checkout failures surface as the code ship_address_required, so no public surface exposes the column name. ~1,000 references.
2. Address: firstname/lastname → first_name/last_name
Serializer: AddressSerializer exposes first_name / last_name.
Controllers: Accept first_name / last_name only.
Model (already existed): Spree::Address has first_name / last_name accessor methods and Spree::PermittedAttributes includes both forms.
Database: done in 6.0. spree_addresses.firstname → first_name, lastname → last_name, with their two hand-named indexes.
3. Address: zipcode → postal_code
Serializer: AddressSerializer exposes postal_code.
Controllers: Accept postal_code only.
Model (already existed): alias_attribute :postal_code, :zipcode on Spree::Address.
Database: done in 6.0. spree_addresses.zipcode → postal_code.
4. CartPromotion/OrderPromotion → Discount
Serializers:
- Created
DiscountSerializer(single serializer for both cart and order promotions) - Deleted
CartPromotionSerializerandOrderPromotionSerializerfiles - Cart/Order serializers:
key: :discountson the association - Admin:
Admin::DiscountSerializerreplacesAdmin::OrderPromotionSerializer
Model aliases: alias discounts order_promotions on Spree::Order
Dependencies: discount_serializer, cart_promotion_serializer, order_promotion_serializer all point to DiscountSerializer. Admin: admin_discount_serializer and admin_order_promotion_serializer point to Admin::DiscountSerializer.
TypeScript type: CartPromotion / OrderPromotion → Discount
5. promo_total → discount_total
Serializers: Cart, Order, LineItem serializers expose discount_total / display_discount_total.
Model aliases:
Spree::Order:alias_attribute :discount_total, :promo_total,alias display_discount_total display_promo_totalSpree::LineItem:alias_attribute :discount_total, :promo_total,alias display_discount_total display_promo_total
Database: done. spree_orders.promo_total moved in 20260729120001; spree_line_items.promo_total and spree_fulfillments.promo_total (not listed originally, but carrying the same inverted alias) moved in the 6.0 pass. spree_carts was born with the new name.
6. WishedItem → WishlistItem
Serializers: Created WishlistItemSerializer, WishlistSerializer references it. Old WishedItemSerializer kept for now (dependency points to new one).
Model alias: alias wishlist_items wished_items on Spree::Wishlist
Dependencies: wishlist_item_serializer and wished_item_serializer both point to WishlistItemSerializer.
Database/model: done in 6.0. Spree::WishedItem → Spree::WishlistItem, table spree_wished_items → spree_wishlist_items. The wi_ prefix is unchanged — see the decision below.
7. special_instructions → customer_note
Serializers: Cart and Order serializers expose customer_note.
Controller: Cart update accepts customer_note only.
Service: Carts::Update assigns cart.customer_note.
Model alias: alias_attribute :customer_note, :special_instructions on Spree::Order
Database: done. Moved in 20260729120001; spree_carts was born with the new name.
8. OptionType/OptionValue: presentation → label
Serializers: OptionTypeSerializer and OptionValueSerializer expose label. OptionValueSerializer exposes option_type_label.
Model aliases: none existed — the label bridge lived only in Spree::PresentationTranslatable (locale-aware label / label= delegations), so the model layer still spoke presentation until the 6.0 rename.
Database: done in 6.0. Both columns, plus the two Mobility translation tables. The bridge is a plain method rather than an alias_attribute — see the decision below.
9. Remove Asset serializer from Store API
AssetSerializer excluded from Store SDK types via Typelizer reject_class filter. Media serializer is the correct Store-facing entity.
10. Exclude admin-only schemas from Store API types
Added Typelizer reject_class filter excluding serializers with no Store API controller:
Asset, CartPromotion, OrderPromotion, StockItem, StockMovement, StockTransfer, ShippingCategory, Reimbursement, Report, Export, Import, ImportRow, TaxCategory, CustomerReturn
11. Slim down Promotion serializer for Store API
PromotionSerializer reduced to: id, name, description, code. Full promotion details remain in Admin serializer only.
12. CreditCard: cc_type → brand, last_digits → last4
Serializer: CreditCardSerializer exposes brand and last4.
Model aliases:
alias_attribute :brand, :cc_type(already existed)alias_attribute :last4, :last_digits(new)
Database: deferred to 6.1. Absent from the v3 contract, never validated, and the aliases already cover read and write, so nothing observable changes.
13. Remove gateway_payment_profile_id from Store API
Removed from CreditCardSerializer and PaymentSourceSerializer. Added to Admin::CreditCardSerializer and Admin::PaymentSourceSerializer.
14. item_count → total_quantity
Serializers: Cart and Order serializers expose total_quantity.
Model alias: alias_attribute :total_quantity, :item_count on Spree::Order
Database: done. Moved in 20260729120001; spree_carts was born with the new name.
15. ReturnAuthorization: state → status
Serializer: ReturnAuthorizationSerializer exposes status (reads object.state).
6.0 database: Covered by 6.0-normalize-state-to-status.md
16. Additional Order model aliases (from 5.4-store-api-bridges)
These aliases consolidate all naming bridges on Spree::Order:
alias fulfillments shipmentsalias_attribute :delivery_total, :shipment_totalalias display_delivery_total display_shipment_totalalias_attribute :fulfillment_status, :shipment_statealias_attribute :payment_status, :payment_state
Implementation Status
Files created
api/app/serializers/spree/api/v3/discount_serializer.rbapi/app/serializers/spree/api/v3/wishlist_item_serializer.rbapi/app/serializers/spree/api/v3/admin/discount_serializer.rb
Files deleted
api/app/serializers/spree/api/v3/cart_promotion_serializer.rbapi/app/serializers/spree/api/v3/order_promotion_serializer.rbapi/app/serializers/spree/api/v3/admin/order_promotion_serializer.rb
Files modified
api/app/serializers/spree/api/v3/address_serializer.rb—firstname→first_name,lastname→last_name,zipcode→postal_codeapi/app/serializers/spree/api/v3/cart_serializer.rb— all renames (customer_note, total_quantity, discount_total, billing/shipping_address, discounts)api/app/serializers/spree/api/v3/order_serializer.rb— same as cartapi/app/serializers/spree/api/v3/line_item_serializer.rb—promo_total→discount_totalapi/app/serializers/spree/api/v3/option_type_serializer.rb—presentation→labelapi/app/serializers/spree/api/v3/option_value_serializer.rb—presentation→label,option_type_presentation→option_type_labelapi/app/serializers/spree/api/v3/credit_card_serializer.rb—cc_type→brand,last_digits→last4, removedgateway_payment_profile_idapi/app/serializers/spree/api/v3/payment_source_serializer.rb— removedgateway_payment_profile_idapi/app/serializers/spree/api/v3/return_authorization_serializer.rb—state→statusapi/app/serializers/spree/api/v3/promotion_serializer.rb— slimmed to name/description/codeapi/app/serializers/spree/api/v3/wishlist_serializer.rb— referenceswishlist_item_serializerapi/app/serializers/spree/api/v3/admin/order_serializer.rb— discounts key, billing/shipping_address keys, admin_discount_serializerapi/app/serializers/spree/api/v3/admin/credit_card_serializer.rb— addedgateway_payment_profile_idapi/app/serializers/spree/api/v3/admin/payment_source_serializer.rb— addedgateway_payment_profile_idapi/app/controllers/spree/api/v3/store/carts_controller.rb— new param names onlyapi/app/controllers/spree/api/v3/store/customer/addresses_controller.rb— new param names onlyapi/lib/spree/api/dependencies.rb— added discount_serializer, wishlist_item_serializer, admin_discount_serializerapi/config/initializers/typelizer.rb— exclude admin-only schemas from Store typescore/app/models/spree/order.rb— all aliases (discount_total, customer_note, total_quantity, billing/shipping_address_id, discounts, fulfillments, etc.)core/app/models/spree/line_item.rb— discount_total aliascore/app/models/spree/option_type.rb— label aliascore/app/models/spree/option_value.rb— label aliascore/app/models/spree/credit_card.rb— last4 aliascore/app/models/spree/wishlist.rb— wishlist_items aliascore/app/services/spree/carts/update.rb— uses new names (shipping_address, billing_address, customer_note)
Integration tests updated
api/spec/integration/spree/api/v3/store/carts_spec.rbapi/spec/integration/spree/api/v3/store/addresses_spec.rbapi/spec/integration/spree/api/v3/store/credit_cards_spec.rb
Test results
- Backend integration tests: 149/149 pass
Shipped in the 6.0 pass (2026-09-02)
- Migrations:
spree_wished_items→spree_wishlist_items;promo_total→discount_totalonspree_line_itemsandspree_fulfillments;firstname/lastname/zipcode→first_name/last_name/postal_codewith their two hand-named indexes;presentation→labelon both option tables and both Mobility translation tables Spree::WishedItem→Spree::WishlistItem(thewi_prefix is unchanged), withwished_item.*events dual-emitted throughSpree::WishlistItem::CustomEventsSpree::PresentationTranslatable→Spree::LabelTranslatable- Types, Zod schemas and the OpenAPI specs regenerated; upgrade guide and developer docs updated
Still TODO
- Nothing for 6.0. The 6.1 alias-removal list gains the bridges this pass added, plus the two deferred renames.
Constraints on Current Work
- All new Store API code must use the new naming from this plan
- Admin API inherits Store serializer renames via inheritance — Admin serializer keys also use new names
- SDK examples and docs must use new naming after this ships
Open Questions
None — all decisions made.
References
5.4-store-api-bridges.md— prior art for this exact pattern6.0-normalize-state-to-status.md— coversstate→statusDB rename- Industry comparison: Shopify, Medusa, Saleor, Vendure, BigCommerce, commercetools Storefront APIs