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.

17.2 KB
Raw Blame

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_code
  • spree_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. The wi_ 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 see
  • spree_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 write
  • spree_orders/spree_carts bill_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 code ship_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 inside where and find_by as well as on an instance.
  • A plain deprecated method (OptionType#presentation, OptionValue#presentation) — instance reads and writes only. Mobility owns label, so an alias_attribute is impossible, and where(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. A DeprecatedConstantProxy would warn but fails is_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 CartPromotionSerializer and OrderPromotionSerializer files
  • Cart/Order serializers: key: :discounts on the association
  • Admin: Admin::DiscountSerializer replaces Admin::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_total
  • Spree::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 shipments
  • alias_attribute :delivery_total, :shipment_total
  • alias display_delivery_total display_shipment_total
  • alias_attribute :fulfillment_status, :shipment_state
  • alias_attribute :payment_status, :payment_state

Implementation Status

Files created

  • api/app/serializers/spree/api/v3/discount_serializer.rb
  • api/app/serializers/spree/api/v3/wishlist_item_serializer.rb
  • api/app/serializers/spree/api/v3/admin/discount_serializer.rb

Files deleted

  • api/app/serializers/spree/api/v3/cart_promotion_serializer.rb
  • api/app/serializers/spree/api/v3/order_promotion_serializer.rb
  • api/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_code
  • api/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 cart
  • api/app/serializers/spree/api/v3/line_item_serializer.rb — promo_total→discount_total
  • api/app/serializers/spree/api/v3/option_type_serializer.rb — presentation→label
  • api/app/serializers/spree/api/v3/option_value_serializer.rb — presentation→label, option_type_presentation→option_type_label
  • api/app/serializers/spree/api/v3/credit_card_serializer.rb — cc_type→brand, last_digits→last4, removed gateway_payment_profile_id
  • api/app/serializers/spree/api/v3/payment_source_serializer.rb — removed gateway_payment_profile_id
  • api/app/serializers/spree/api/v3/return_authorization_serializer.rb — state→status
  • api/app/serializers/spree/api/v3/promotion_serializer.rb — slimmed to name/description/code
  • api/app/serializers/spree/api/v3/wishlist_serializer.rb — references wishlist_item_serializer
  • api/app/serializers/spree/api/v3/admin/order_serializer.rb — discounts key, billing/shipping_address keys, admin_discount_serializer
  • api/app/serializers/spree/api/v3/admin/credit_card_serializer.rb — added gateway_payment_profile_id
  • api/app/serializers/spree/api/v3/admin/payment_source_serializer.rb — added gateway_payment_profile_id
  • api/app/controllers/spree/api/v3/store/carts_controller.rb — new param names only
  • api/app/controllers/spree/api/v3/store/customer/addresses_controller.rb — new param names only
  • api/lib/spree/api/dependencies.rb — added discount_serializer, wishlist_item_serializer, admin_discount_serializer
  • api/config/initializers/typelizer.rb — exclude admin-only schemas from Store types
  • core/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 alias
  • core/app/models/spree/option_type.rb — label alias
  • core/app/models/spree/option_value.rb — label alias
  • core/app/models/spree/credit_card.rb — last4 alias
  • core/app/models/spree/wishlist.rb — wishlist_items alias
  • core/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.rb
  • api/spec/integration/spree/api/v3/store/addresses_spec.rb
  • api/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_total on spree_line_items and spree_fulfillments; firstname/lastname/zipcode → first_name/last_name/postal_code with their two hand-named indexes; presentation → label on both option tables and both Mobility translation tables
  • Spree::WishedItem → Spree::WishlistItem (the wi_ prefix is unchanged), with wished_item.* events dual-emitted through Spree::WishlistItem::CustomEvents
  • Spree::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 pattern
  • 6.0-normalize-state-to-status.md — covers state → status DB rename
  • Industry comparison: Shopify, Medusa, Saleor, Vendure, BigCommerce, commercetools Storefront APIs