spree_api 5.6.1 → 6.0.0.beta1

data/app/serializers/spree/api/v3/order_serializer.rb

@@ -4,11 +4,18 @@ module Spree
       # Store API Order Serializer
       # Post-purchase order data (completed orders)
       class OrderSerializer < BaseSerializer
-        typelize number: :string, email: :string,
+        typelize cart_id: [:string, nullable: true],
+                 number: :string, email: :string,
                  customer_note: [:string, nullable: true],
                  market_id: [:string, nullable: true], channel_id: [:string, nullable: true],
+                 company_id: [:string, nullable: true], company_name: [:string, nullable: true],
+                 po_number: [:string, nullable: true],
+                 po_document_filename: [:string, nullable: true],
+                 po_document_byte_size: ['number | null'],
                  currency: :string, locale: [:string, nullable: true], total_quantity: :number,
-                 fulfillment_status: [:string, nullable: true], payment_status: [:string, nullable: true],
+                 coupon_code: [:string, nullable: true],
+                 fulfillment_status: [:string, nullable: true, enum: Spree::Order::FULFILLMENT_STATUSES],
+                 payment_status: [:string, nullable: true, enum: Spree::Order::PAYMENT_STATUSES],
                  item_total: [:string, nullable: true], display_item_total: [:string, nullable: true],
                  delivery_total: [:string, nullable: true], display_delivery_total: [:string, nullable: true],
                  adjustment_total: [:string, nullable: true], display_adjustment_total: [:string, nullable: true],
@@ -16,12 +23,15 @@ module Spree
                  tax_total: [:string, nullable: true], display_tax_total: [:string, nullable: true],
                  included_tax_total: [:string, nullable: true], display_included_tax_total: [:string, nullable: true],
                  additional_tax_total: [:string, nullable: true], display_additional_tax_total: [:string, nullable: true],
+                 fee_total: [:string, nullable: true], display_fee_total: [:string, nullable: true],
                  store_credit_total: [:string, nullable: true], display_store_credit_total: [:string, nullable: true],
                  gift_card_total: [:string, nullable: true], display_gift_card_total: [:string, nullable: true],
                  covered_by_store_credit: :boolean,
                  total: [:string, nullable: true], display_total: [:string, nullable: true],
                  amount_due: [:string, nullable: true], display_amount_due: [:string, nullable: true],
                  completed_at: [:string, nullable: true],
+                 withdrawal_period_ends_at: [:string, nullable: true],
+                 within_withdrawal_period: :boolean,
                  billing_address: { nullable: true }, shipping_address: { nullable: true },
                  gift_card: { nullable: true }, market: { nullable: true }
 
@@ -29,12 +39,50 @@ module Spree
           order.market&.prefixed_id
         end
 
+        # The EU cooling-off deadline. Customer-facing by design: a buyer
+        # deciding whether they can still send something back should not have
+        # to work the date out from a policy page.
+        attribute :withdrawal_period_ends_at do |order|
+          order.withdrawal_period_ends_at&.iso8601
+        end
+
+        attribute :within_withdrawal_period do |order|
+          order.within_withdrawal_period?
+        end
+
+        # The checkout handle this order was born from (nil for admin drafts).
+        # Lets abandonment tooling match cart.* events to the conversion.
+        # Encoded from the FK — loading the cart row just for its id would be
+        # an N+1 on order lists.
+        attribute :cart_id do |order|
+          Spree::Cart.prefixed_id_for(order.cart_id)
+        end
+
         attribute :channel_id do |order|
           order.channel&.prefixed_id
         end
 
-        attributes :number, :email, :customer_note,
-                   :currency, :locale, :total_quantity,
+        # Which company node the order was placed for — frozen at completion.
+        attribute :company_id do |order|
+          order.company&.prefixed_id
+        end
+
+        attribute :company_name do |order|
+          order.company&.name
+        end
+
+        # The buyer's own purchase-order reference, carried from the cart. Their
+        # accounting reconciles against it, so it stays on the order forever.
+        attribute :po_document_filename do |order|
+          order.po_document.blob&.filename&.to_s if order.po_document.attached?
+        end
+
+        attribute :po_document_byte_size do |order|
+          order.po_document.blob&.byte_size if order.po_document.attached?
+        end
+
+        attributes :number, :email, :customer_note, :po_number,
+                   :currency, :locale, :total_quantity, :coupon_code,
                    :fulfillment_status, :payment_status,
                    completed_at: :iso8601
 
@@ -47,7 +95,8 @@ module Spree
                          :additional_tax_total, :display_additional_tax_total, :total, :display_total,
                          :gift_card_total, :display_gift_card_total,
                          :amount_due, :display_amount_due,
-                         :delivery_total, :display_delivery_total
+                         :delivery_total, :display_delivery_total,
+                         :fee_total, :display_fee_total
 
         attribute :store_credit_total do |order|
           order.total_applied_store_credit.to_s unless params[:hide_prices]
@@ -61,7 +110,10 @@ module Spree
           order.covered_by_store_credit?
         end
 
-        many :discounts, resource: proc { Spree.api.discount_serializer }
+        many :order_promotions, key: :discounts, resource: proc { Spree.api.applied_promotion_serializer }
+        # Itemized charges (duties, surcharges, COD, handling) — see the cart
+        # serializer; the order keeps them visible after placement.
+        many :fees, resource: proc { Spree.api.fee_serializer }
         many :line_items, key: :items, resource: proc { Spree.api.line_item_serializer }
         many :fulfillments, resource: proc { Spree.api.fulfillment_serializer }
         many :payments, resource: proc { Spree.api.payment_serializer }

data/app/serializers/spree/api/v3/payment_method_serializer.rb

@@ -2,7 +2,7 @@ module Spree
   module Api
     module V3
       class PaymentMethodSerializer < BaseSerializer
-        typelize name: :string, description: [:string, nullable: true], type: :string,
+        typelize name: :string, description: [:string, nullable: true], type: [:string, comment: 'Payment method type. Built-in: check, store_credit, custom_payment_source_method, bogus (test only); payment provider gems register their own, for example stripe.'],
                  session_required: :boolean, source_required: :boolean
 
         attributes :name, :description

data/app/serializers/spree/api/v3/payment_serializer.rb

@@ -2,7 +2,7 @@ module Spree
   module Api
     module V3
       class PaymentSerializer < BaseSerializer
-        typelize status: :string, payment_method_id: :string, response_code: [:string, nullable: true],
+        typelize status: [:string, enum: Spree::Payment.statuses, enum_type_name: 'PaymentStatus'], payment_method_id: :string, response_code: [:string, nullable: true],
                  number: :string, amount: [:string, nullable: true], display_amount: [:string, nullable: true],
                  source_type: [:string, nullable: true, enum: %w[credit_card store_credit payment_source]],
                  source_id: [:string, nullable: true],
@@ -12,16 +12,12 @@ module Spree
           payment.payment_method&.prefixed_id
         end
 
-        attributes :response_code, :number
+        attributes :response_code, :number, :status
 
         # Nulled for gated (prices_hidden) guests so a payment can't leak the
         # amount the cart/order totals already withhold.
         money_attributes :amount, :display_amount
 
-        attribute :status do |payment|
-          payment.state
-        end
-
         attribute :source_type do |payment|
           case payment.source_type
           when 'Spree::CreditCard'

data/app/serializers/spree/api/v3/payment_session_serializer.rb

@@ -2,10 +2,11 @@ module Spree
   module Api
     module V3
       class PaymentSessionSerializer < BaseSerializer
-        typelize status: :string, amount: :string, currency: :string,
+        typelize status: [:string, enum: Spree::PaymentSession.statuses, enum_type_name: 'PaymentSessionStatus'], amount: :string, currency: :string,
                  external_id: :string, external_data: 'Record<string, unknown>',
                  expires_at: [:string, nullable: true], customer_external_id: [:string, nullable: true],
-                 payment_method_id: :string, order_id: :string
+                 payment_method_id: :string, order_id: [:string, nullable: true],
+                 cart_id: [:string, nullable: true]
 
         attributes :status, :currency, :external_id, :external_data,
                    :customer_external_id,
@@ -19,8 +20,14 @@ module Spree
           session.payment_method&.prefixed_id
         end
 
+        # Bridge: reports the owner (cart during checkout, order after
+        # completion) until clients migrate to cart_id/order_id.
         attribute :order_id do |session|
-          session.order&.prefixed_id
+          session.owner&.prefixed_id
+        end
+
+        attribute :cart_id do |session|
+          session.cart&.prefixed_id
         end
 
         one :payment_method, resource: proc { Spree.api.payment_method_serializer }

data/app/serializers/spree/api/v3/payment_setup_session_serializer.rb

@@ -2,7 +2,7 @@ module Spree
   module Api
     module V3
       class PaymentSetupSessionSerializer < BaseSerializer
-        typelize status: :string, external_id: [:string, nullable: true], external_client_secret: [:string, nullable: true],
+        typelize status: [:string, enum: Spree::PaymentSetupSession.statuses, enum_type_name: 'PaymentSetupSessionStatus'], external_id: [:string, nullable: true], external_client_secret: [:string, nullable: true],
                  external_data: 'Record<string, unknown>',
                  payment_method_id: [:string, nullable: true], payment_source_id: [:string, nullable: true],
                  payment_source_type: [:string, nullable: true], customer_id: [:string, nullable: true]

data/app/serializers/spree/api/v3/policy_serializer.rb

@@ -8,13 +8,18 @@ module Spree
         attributes :name, :slug
 
         attribute :body do |policy|
-          policy.body&.to_plain_text
+          Spree::RichTextHelper.to_plain_text(policy.body)
         end
 
         attribute :body_html do |policy|
-          policy.body&.body&.to_s.to_s
+          policy.body_html
         end
 
+        # The one timestamp a store serializer carries. When a legal document
+        # last changed is what a shopper is entitled to see on the page —
+        # "last updated" is the convention for policies — not operational
+        # detail. `created_at` stays admin-only.
+        attributes updated_at: :iso8601
       end
     end
   end

data/app/serializers/spree/api/v3/product_filter_option_serializer.rb

@@ -6,7 +6,7 @@ module Spree
                  type: "'option'",
                  name: :string,
                  label: :string,
-                 kind: :string,
+                 kind: [:string, enum: Spree::OptionType::KINDS],
                  options: [:ProductFilterOptionValue, multi: true]
 
         attributes :id, :type, :name, :label, :kind

data/app/serializers/spree/api/v3/product_serializer.rb

@@ -9,6 +9,7 @@ module Spree
                  meta_description: [:string, nullable: true], meta_keywords: [:string, nullable: true],
                  variant_count: :number,
                  default_variant_id: :string,
+                 buy_box_variant_id: [:string, nullable: true],
                  thumbnail_url: [:string, nullable: true],
                  available_on: [:string, nullable: true],
                  preorder_ships_at: [:string, nullable: true],
@@ -55,10 +56,23 @@ module Spree
           product.description
         end
 
+        # The product's stable identity for add-to-cart. Deliberately NOT the
+        # buy-box winner: that moves with price and stock, and a client that
+        # cached or linked this id must not find it pointing at a different
+        # row tomorrow. On a single-seller catalog the two coincide anyway.
         attribute :default_variant_id do |product|
           product.default_variant&.prefixed_id
         end
 
+        # The offer a storefront should lead with when several sellers share
+        # the listing — the buy-box winner in the request's currency. Nil when
+        # nothing wins. Separate from `default_variant_id` so a storefront opts
+        # into the marketplace behaviour without the identity field moving
+        # under it; storefronts that ignore it lose nothing.
+        attribute :buy_box_variant_id do |product|
+          product.buy_box_variant(currency: current_currency)&.prefixed_id
+        end
+
         # Main product image URL for listings (cached primary_media)
         attribute :thumbnail_url do |product|
           image_url_for(product.primary_media)
@@ -68,16 +82,22 @@ module Spree
           product.tags.map(&:name) # not pluck as we preload tags
         end
 
-        # Price object - calculated price with price list resolution
+        # Price object - calculated price with price list resolution.
+        #
+        # Priced off the buy-box winner, not `default_variant_id`. Price is a
+        # display fact that already moves with price lists and currency, so it
+        # is not an identity — and it must agree with `buy_box_variant_id`: the
+        # price a shopper sees is the price of the offer they are shown. On a
+        # single-seller catalog winner and default variant are the same row.
         attribute :price do |product|
-          price = price_for(product.default_variant)
+          price = price_for(featured_variant(product))
           Spree.api.price_serializer.new(price, params: params).to_h if price.present?
         end
 
         # Original price - base price without price list resolution (for showing strikethrough)
         # Returns null when same as calculated price, only populated when a price list discount is applied
         attribute :original_price do |product|
-          variant = product.default_variant
+          variant = featured_variant(product)
           calculated = price_for(variant)
           base = price_in(variant)
 
@@ -86,7 +106,18 @@ module Spree
           end
         end
 
+        # Nil on the marketplace's own first-party products. The id is always
+        # present so a storefront can group or link by seller without paying
+        # for the expand; `?expand=seller` adds the public profile.
+        attribute :seller_id do |product|
+          product.seller&.prefixed_id
+        end
+
         # Conditional associations
+        one :seller,
+            resource: proc { Spree.api.seller_serializer },
+            if: proc { expand?('seller') }
+
         one :primary_media,
             resource: proc { Spree.api.media_serializer },
             if: proc { expand?('primary_media') }
@@ -112,24 +143,25 @@ module Spree
              resource: proc { Spree.api.option_value_serializer },
              if: proc { expand?('option_values') }
 
-        many :taxons,
-             proc { |taxons, params|
-               taxons.select { |t| t.taxonomy.store_id == params[:store].id }
+        many :categories,
+             proc { |categories, params|
+               store_id = params[:store].id
+               categories.select { |c| c.store_id == store_id }
              },
-             key: :categories,
              resource: proc { Spree.api.category_serializer },
              if: proc { expand?('categories') }
 
-        many :public_metafields,
+        many :storefront_custom_fields,
              key: :custom_fields,
              resource: proc { Spree.api.custom_field_serializer },
              if: proc { expand?('custom_fields') }
 
-        typelize prior_price: ['PriceHistory', nullable: true]
+        typelize prior_price: ['PriceHistory', nullable: true],
+                 seller_id: [:string, nullable: true]
 
         attribute :prior_price,
                   if: proc { expand?('prior_price') } do |product|
-          record = price_in(product.default_variant)&.prior_price
+          record = price_in(featured_variant(product))&.prior_price
           Spree.api.price_history_serializer.new(record, params: params).to_h if record
         end
       end

data/app/serializers/spree/api/v3/product_type_serializer.rb

@@ -0,0 +1,17 @@
+module Spree
+  module Api
+    module V3
+      # Base Product Type Serializer.
+      #
+      # ProductType is back-office vocabulary and is NOT exposed on the Store
+      # API — no endpoint, no expand, no filter. This class exists solely as the
+      # parent of the Admin serializer, per the house convention that every
+      # admin serializer extends a store-namespace base.
+      class ProductTypeSerializer < BaseSerializer
+        typelize name: :string
+
+        attributes :name
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/purchase_order_event_serializer.rb

@@ -0,0 +1,11 @@
+module Spree
+  module Api
+    module V3
+      # Payload of the purchase_order.* events. Purchase orders have no
+      # storefront serializer, so the event shape is declared here rather than
+      # found by convention.
+      class PurchaseOrderEventSerializer < Admin::PurchaseOrderSerializer
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/refund_serializer.rb

@@ -6,7 +6,7 @@ module Spree
       class RefundSerializer < BaseSerializer
         typelize amount: [:string, nullable: true], transaction_id: [:string, nullable: true],
                  payment_id: [:string, nullable: true], refund_reason_id: [:string, nullable: true],
-                 reimbursement_id: [:string, nullable: true]
+                 originator_id: [:string, nullable: true], originator_type: [:string, nullable: true]
 
         attributes :transaction_id
 
@@ -22,8 +22,14 @@ module Spree
           refund.reason&.prefixed_id
         end
 
-        attribute :reimbursement_id do |refund|
-          refund.reimbursement&.prefixed_id
+        # What triggered this refund — a Return, Exchange or Claim; nil for a
+        # manual refund.
+        attribute :originator_id do |refund|
+          refund.originator&.prefixed_id
+        end
+
+        attribute :originator_type do |refund|
+          refund.originator_type
         end
       end
     end

data/app/serializers/spree/api/v3/return_line_item_serializer.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Spree
+  module Api
+    module V3
+      class ReturnLineItemSerializer < BaseSerializer
+        typelize quantity: :number,
+                 received_quantity: :number,
+                 resellable: :boolean,
+                 pre_tax_amount: :string,
+                 display_pre_tax_amount: :string,
+                 variant_id: [:string, nullable: true],
+                 line_item_id: [:string, nullable: true],
+                 fulfillment_item_id: [:string, nullable: true]
+
+        attributes :quantity, :received_quantity, :resellable
+
+        attribute :pre_tax_amount do |line|
+          line.pre_tax_amount.to_s
+        end
+
+        attribute :display_pre_tax_amount do |line|
+          line.display_pre_tax_amount.to_s
+        end
+
+        attribute :variant_id do |line|
+          line.variant&.prefixed_id
+        end
+
+        attribute :line_item_id do |line|
+          line.line_item&.prefixed_id
+        end
+
+        attribute :fulfillment_item_id do |line|
+          line.fulfillment_item&.prefixed_id
+        end
+
+        one :variant, resource: proc { Spree.api.variant_serializer }, if: proc { expand?('variant') }
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/return_reason_serializer.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Spree
+  module Api
+    module V3
+      # Why a customer sent something back. Embedded in returns and exchanges
+      # so a customer sees the reason's name rather than only its id; the
+      # vocabulary itself has no Store API controller of its own.
+      #
+      # Parallel to ClaimReasonSerializer rather than sharing a base class:
+      # Typelizer emits one TS type per serializer, so a shared parent would
+      # publish an abstract `Reason` type that no endpoint returns.
+      class ReturnReasonSerializer < BaseSerializer
+        typelize name: :string, active: :boolean
+
+        attributes :name, :active
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/return_serializer.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Spree
+  module Api
+    module V3
+      # Customer-facing view of a return. No timestamps, no internal notes,
+      # no staff attribution — see the serializer rules in CLAUDE.md.
+      class ReturnSerializer < BaseSerializer
+        typelize number: :string,
+                 status: [:string, enum: Spree::Return.statuses, enum_type_name: 'ReturnStatus'],
+                 order_id: [:string, nullable: true],
+                 reason_id: [:string, nullable: true],
+                 refund_total: :string,
+                 display_refund_total: :string,
+                 approved_at: [:string, nullable: true],
+                 received_at: [:string, nullable: true],
+                 refunded_at: [:string, nullable: true],
+                 canceled_at: [:string, nullable: true]
+
+        attributes :number, :status
+
+        attribute :order_id do |return_record|
+          return_record.order&.prefixed_id
+        end
+
+        attribute :reason_id do |return_record|
+          return_record.reason&.prefixed_id
+        end
+
+        attribute :refund_total do |return_record|
+          return_record.refund_total.to_s
+        end
+
+        attribute :display_refund_total do |return_record|
+          return_record.display_refund_total.to_s
+        end
+
+        attribute :approved_at do |return_record|
+          return_record.approved_at&.iso8601
+        end
+
+        attribute :received_at do |return_record|
+          return_record.received_at&.iso8601
+        end
+
+        attribute :refunded_at do |return_record|
+          return_record.refunded_at&.iso8601
+        end
+
+        attribute :canceled_at do |return_record|
+          return_record.canceled_at&.iso8601
+        end
+
+        one :reason, resource: proc { Spree.api.return_reason_serializer }, if: proc { expand?('reason') }
+
+        many :return_line_items,
+             resource: proc { Spree.api.return_line_item_serializer },
+             if: proc { expand?('return_line_items') }
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/seller/balance_serializer.rb

@@ -0,0 +1,35 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # This seller's position in one currency (Spree::SellerBalance).
+        #
+        # A computed value rather than a record, so it carries no id.
+        class BalanceSerializer < V3::BaseSerializer
+          typelize currency: :string,
+                   settlement_currency: :string,
+                   converted: :boolean,
+                   earned: :string, display_earned: :string,
+                   payable: :string, display_payable: :string,
+                   paid: :string, display_paid: :string,
+                   balance: :string, display_balance: :string,
+                   pending: :string, display_pending: :string
+
+          _attributes.delete(:id)
+
+          # Two sides when the account settles in another currency: what the
+          # sales were worth, and what the account received once the provider
+          # converted. Never added together.
+          attributes :currency, :settlement_currency
+
+          attribute(:converted) { |balance| balance.converted? }
+
+          %i[earned payable paid balance pending].each do |figure|
+            attribute(figure) { |balance| balance.public_send(figure).to_s }
+            attribute(:"display_#{figure}") { |balance| balance.public_send(:"display_#{figure}").to_s }
+          end
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/seller/claim_line_item_serializer.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Spree
+  module Api
+    module V3
+      module Seller
+        # One line of a claim — what went wrong, and what is being sent or
+        # refunded to put it right.
+        class ClaimLineItemSerializer < V3::ClaimLineItemSerializer
+          typelize name: [:string, nullable: true]
+
+          attribute :name do |line|
+            line.line_item&.name || line.variant&.name
+          end
+
+          one :variant, resource: proc { Spree.api.seller_variant_serializer }, if: proc { expand?('variant') }
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/seller/claim_serializer.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Spree
+  module Api
+    module V3
+      module Seller
+        # A claim on one of this seller's orders.
+        #
+        # Built on the shared V3 serializer rather than the admin one, which
+        # expands the order and the customer behind it.
+        class ClaimSerializer < V3::ClaimSerializer
+          typelize memo: [:string, nullable: true]
+
+          attributes :memo
+
+          many :claim_line_items,
+               resource: proc { Spree.api.seller_claim_line_item_serializer },
+               if: proc { expand?('claim_line_items') }
+
+          one :reason, resource: proc { Spree.api.seller_reason_serializer }, if: proc { expand?('reason') }
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/seller/delivery_method_rule_serializer.rb

@@ -0,0 +1,32 @@
+module Spree
+  module Api
+    module V3
+      module Seller
+        # One condition on a seller's delivery method — "orders over $50",
+        # "under 20kg".
+        #
+        # Declared rather than subclassed from the admin serializer, like
+        # every serializer on this branch. `product_ids` is absent: the rules
+        # a seller may use are preference-only (see the seller delivery
+        # methods controller), so no rule here carries an association.
+        class DeliveryMethodRuleSerializer < BaseSerializer
+          typelize type: [:string, comment: 'Rule type. Built-in: item_total_rule, weight_rule, excluded_products_rule, channel_rule, volume_rule, company_rule. Extensions may register more.'],
+                   active: :boolean,
+                   preferences: 'Record<string, unknown>',
+                   preference_schema: "Array<{ key: string; type: string; default: unknown; choices?: string[] }>"
+
+          attributes :active
+
+          # Wire shorthand (e.g. `item_total_rule`), matching the types
+          # discovery endpoint.
+          attribute :type do |rule|
+            rule.class.api_type
+          end
+
+          attribute :preferences, &:serialized_preferences
+          attribute :preference_schema, &:serialized_preference_schema
+        end
+      end
+    end
+  end
+end