spree_api 5.6.1 → 6.0.0.beta1

data/app/serializers/spree/api/v3/admin/store_serializer.rb

@@ -6,6 +6,7 @@ module Spree
           typelize name: :string, url: :string, code: :string, api_url: :string,
                    preferred_storefront_url: [:string, nullable: true],
                    default_currency: :string, default_locale: :string,
+                   default_country_code: [:string, nullable: true],
                    supported_currencies: [:string, multi: true],
                    supported_locales: [:string, multi: true],
                    available_locales: [:string, multi: true],
@@ -17,11 +18,38 @@ module Spree
                    preferred_send_consumer_transactional_emails: :boolean,
                    preferred_admin_locale: [:string, nullable: true],
                    preferred_timezone: :string,
-                   preferred_weight_unit: :string,
+                   preferred_weight_unit: [:string, enum: Spree::Variant::WEIGHT_UNITS],
                    preferred_unit_system: :string,
                    preferred_storefront_access: :string,
                    preferred_guest_checkout: :boolean,
+                   preferred_company_field_enabled: :boolean,
+                   preferred_address_requires_company: :boolean,
+                   preferred_address_requires_phone: :boolean,
+                   preferred_capture_method: :string,
+                   preferred_track_inventory_levels: :boolean,
+                   preferred_stock_reservations_enabled: :boolean,
+                   preferred_low_stock_threshold: :number,
+                   preferred_tax_using_ship_address: :boolean,
+                   preferred_track_price_history: :boolean,
+                   preferred_show_products_without_price: :boolean,
+                   preferred_disable_sku_validation: :boolean,
                    preferred_order_routing_strategy: :string,
+                   preferred_pricing_provider: :string,
+                   preferred_inventory_provider: :string,
+                   preferred_pricing_provider_failure_policy: :string,
+                   preferred_inventory_provider_failure_policy: :string,
+                   preferred_payout_provider: 'string | null',
+                   preferred_default_payouts_schedule_interval: :string,
+                   preferred_default_minimum_payout_amount: :number,
+                   preferred_document_number_format: :string,
+                   preferred_order_number_prefix: :string,
+                   preferred_order_number_suffix: :string,
+                   preferred_order_number_sequence_start: :number,
+                   order_number_sequence_started: :boolean,
+                   preferred_limit_digital_download_count: :boolean,
+                   preferred_digital_asset_authorized_clicks: :number,
+                   preferred_limit_digital_download_days: :boolean,
+                   preferred_digital_asset_authorized_days: :number,
                    metadata: 'Record<string, unknown>'
 
           attributes :metadata,
@@ -30,6 +58,7 @@ module Spree
                      :preferred_storefront_url,
                      :default_currency,
                      :default_locale,
+                     :default_country_code,
                      :mail_from_address,
                      :customer_support_email,
                      :new_order_notifications_email,
@@ -40,9 +69,42 @@ module Spree
                      :preferred_unit_system,
                      :preferred_storefront_access,
                      :preferred_guest_checkout,
+                     :preferred_company_field_enabled,
+                     :preferred_address_requires_company,
+                     :preferred_address_requires_phone,
+                     :preferred_capture_method,
+                     :preferred_track_inventory_levels,
+                     :preferred_stock_reservations_enabled,
+                     :preferred_low_stock_threshold,
+                     :preferred_tax_using_ship_address,
+                     :preferred_track_price_history,
+                     :preferred_show_products_without_price,
+                     :preferred_disable_sku_validation,
                      :preferred_order_routing_strategy,
+                     :preferred_pricing_provider,
+                     :preferred_inventory_provider,
+                     :preferred_pricing_provider_failure_policy,
+                     :preferred_inventory_provider_failure_policy,
+                     :preferred_payout_provider,
+                     :preferred_default_payouts_schedule_interval,
+                     :preferred_default_minimum_payout_amount,
+                     :preferred_document_number_format,
+                     :preferred_order_number_prefix,
+                     :preferred_order_number_suffix,
+                     :preferred_order_number_sequence_start,
+                     :preferred_limit_digital_download_count,
+                     :preferred_digital_asset_authorized_clicks,
+                     :preferred_limit_digital_download_days,
+                     :preferred_digital_asset_authorized_days,
                      created_at: :iso8601, updated_at: :iso8601
 
+          # Once the counter has issued a number the starting value no longer
+          # applies, so the settings page can say that instead of accepting a
+          # value that does nothing.
+          attribute :order_number_sequence_started do |store|
+            Spree::NumberSequence.started?(store: store)
+          end
+
           attribute :url, &:storefront_url
 
           # The backend's own public URL — what a headless client sets as its

data/app/serializers/spree/api/v3/admin/supplier_serializer.rb

@@ -0,0 +1,39 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Admin-only: who the merchant buys from is never a storefront
+        # concern.
+        class SupplierSerializer < V3::BaseSerializer
+          typelize name: :string,
+                   contact_name: 'string | null',
+                   email: 'string | null',
+                   phone: 'string | null',
+                   notes: 'string | null',
+                   address1: 'string | null',
+                   address2: 'string | null',
+                   city: 'string | null',
+                   state_name: 'string | null',
+                   state_code: 'string | null',
+                   country_code: 'string | null',
+                   postal_code: 'string | null',
+                   purchase_orders_count: :number,
+                   can_be_deleted: :boolean,
+                   deleted_at: 'string | null',
+                   metadata: 'Record<string, unknown>'
+
+          attributes :name, :contact_name, :email, :phone, :notes,
+                     :address1, :address2, :city, :state_name, :state_code,
+                     :country_code, :postal_code, :purchase_orders_count, :metadata,
+                     created_at: :iso8601, updated_at: :iso8601, deleted_at: :iso8601
+
+          # Lets the dashboard hide the delete control rather than offer one
+          # the model will refuse.
+          attribute :can_be_deleted do |supplier|
+            supplier.can_be_deleted?
+          end
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/tax_exemption_certificate_serializer.rb

@@ -0,0 +1,67 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Admin-only: certificates are back-office evidence with no storefront
+        # surface, so there is no store serializer to extend.
+        class TaxExemptionCertificateSerializer < V3::BaseSerializer
+          typelize certificate_number: :string, reason_code: :string, status: [:string, enum: Spree::TaxExemptionCertificate.statuses, enum_type_name: 'TaxExemptionCertificateStatus'],
+                   issuing_authority: [:string, nullable: true],
+                   company_id: :string,
+                   country_code: [:string, nullable: true], state_code: [:string, nullable: true],
+                   active: :boolean, lapsed: :boolean, can_be_deleted: :boolean,
+                   document_filename: [:string, nullable: true],
+                   document_byte_size: ['number | null'],
+                   document_url: [:string, nullable: true],
+                   metadata: 'Record<string, unknown> | null'
+
+          attributes :certificate_number, :reason_code, :status, :issuing_authority, :metadata,
+                     issued_at: :iso8601, expires_at: :iso8601, verified_at: :iso8601,
+                     created_at: :iso8601, updated_at: :iso8601
+
+          attribute :company_id do |certificate|
+            certificate.company&.prefixed_id
+          end
+
+          # The jurisdiction the certificate holds in, in the same vocabulary the
+          # tax lines use.
+          attributes :country_code, :state_code
+
+          # Whether it counts right now — the status alone can't say, since a
+          # verified certificate stops counting once its date passes.
+          attribute :active do |certificate|
+            certificate.verified? && !certificate.lapsed?
+          end
+
+          attribute :lapsed do |certificate|
+            certificate.lapsed?
+          end
+
+          # Lets the dashboard hide a delete the model will refuse.
+          attribute :can_be_deleted do |certificate|
+            certificate.can_be_deleted?
+          end
+
+          attribute :document_filename do |certificate|
+            certificate.document.blob&.filename&.to_s if certificate.document.attached?
+          end
+
+          attribute :document_byte_size do |certificate|
+            certificate.document.blob&.byte_size if certificate.document.attached?
+          end
+
+          # Our own endpoint rather than a pre-signed URL: the controller streams
+          # the bytes, so admin auth runs on every download of a confidential
+          # document.
+          attribute :document_url do |certificate|
+            next nil unless certificate.document.attached?
+
+            Spree::Core::Engine.routes.url_helpers.download_api_v3_admin_company_tax_exemption_certificate_path(
+              company_id: certificate.company.prefixed_id, id: certificate.prefixed_id
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/tax_identifier_serializer.rb

@@ -0,0 +1,43 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        class TaxIdentifierSerializer < V3::TaxIdentifierSerializer
+          typelize validation_status: [:string, nullable: true, enum: Spree::TaxIdentifier::VALIDATION_STATUSES],
+                   validated_at: [:string, nullable: true],
+                   validation_evidence: ['Record<string, unknown>', nullable: true],
+                   source: [:string, nullable: true, enum: Spree::TaxIdentifier::SOURCES],
+                   validatable: :boolean,
+                   customer_id: [:string, nullable: true],
+                   cart_id: [:string, nullable: true],
+                   order_id: [:string, nullable: true]
+
+          attributes :validation_status, :validation_evidence, :source,
+                     validated_at: :iso8601, created_at: :iso8601, updated_at: :iso8601
+
+          # Whether this installation can check a number of this kind at all —
+          # what tells a nil verdict "not checked yet" apart from "nothing here
+          # knows how to ask".
+          attribute :validatable do |tax_identifier|
+            tax_identifier.validatable?
+          end
+
+          # The owner, reported under the name of what it is, so a client can
+          # tell a customer's durable registration from a cart override or an
+          # order's snapshot without reading a type string.
+          attribute :customer_id do |tax_identifier|
+            tax_identifier.owner&.prefixed_id if tax_identifier.owner.is_a?(Spree.customer_class)
+          end
+
+          attribute :cart_id do |tax_identifier|
+            tax_identifier.owner&.prefixed_id if tax_identifier.owner.is_a?(Spree::Cart)
+          end
+
+          attribute :order_id do |tax_identifier|
+            tax_identifier.owner&.prefixed_id if tax_identifier.owner.is_a?(Spree::Order)
+          end
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/tax_line_serializer.rb

@@ -0,0 +1,21 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        class TaxLineSerializer < V3::TaxLineSerializer
+          typelize amount: [:string, nullable: false], display_amount: [:string, nullable: false],
+                   provider_id: [:string, nullable: true], metadata: ['Record<string, unknown>', nullable: true],
+                   taxability_reason: [:string, nullable: true], country_code: [:string, nullable: true],
+                   state_code: [:string, nullable: true], data: ['Record<string, unknown>', nullable: true]
+
+          # The treatment and its jurisdiction stay admin-only: no surveyed
+          # platform shows a buyer a machine-readable tax reason, and `label`
+          # already covers what they need. `data` carries the provider's own
+          # breakdown, which is what an e-invoicing integration reads.
+          attributes :provider_id, :metadata, :taxability_reason, :country_code, :state_code, :data,
+                     created_at: :iso8601, updated_at: :iso8601
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/tax_rate_serializer.rb

@@ -0,0 +1,49 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Admin-only: tax rates are the internal provider's configuration, never
+        # customer-facing. What the customer sees is the label on a tax line.
+        class TaxRateSerializer < V3::BaseSerializer
+          typelize name: :string,
+                   amount: :string,
+                   amount_percentage: [:number, nullable: true],
+                   included_in_price: :boolean,
+                   show_rate_in_label: :boolean,
+                   tax_category_id: [:string, nullable: true],
+                   store_id: [:string, nullable: true],
+                   country_code: [:string, nullable: true],
+                   state_code: [:string, nullable: true],
+                   metadata: ['Record<string, unknown>', nullable: true],
+                   deleted_at: [:string, nullable: true]
+
+          attributes :name, :included_in_price, :show_rate_in_label, :metadata,
+                     created_at: :iso8601, updated_at: :iso8601, deleted_at: :iso8601
+
+          attribute :amount do |tax_rate|
+            tax_rate.amount&.to_s
+          end
+
+          # A real number, unlike the money-style `amount` string — this is a
+          # percentage for display, not an amount to round-trip exactly.
+          attribute :amount_percentage do |tax_rate|
+            tax_rate.amount_percentage&.to_f
+          end
+
+          attribute :tax_category_id do |tax_rate|
+            tax_rate.tax_category&.prefixed_id
+          end
+
+          attribute :store_id do |tax_rate|
+            tax_rate.store&.prefixed_id
+          end
+
+          # The jurisdiction the rate taxes, as codes: a null country means every
+          # country, and a country with no state means the whole country. Read
+          # and written under the same two names.
+          attributes :country_code, :state_code
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/admin/variant_serializer.rb

@@ -5,21 +5,38 @@ module Spree
         # Admin API Variant Serializer
         # Full variant data including admin-only fields
         class VariantSerializer < V3::VariantSerializer
+          include Concerns::ExternalReferencesAttribute
+
 
           typelize product_name: :string,
                    position: :number, tax_category_id: [:string, nullable: true],
                    cost_price: [:string, nullable: true], cost_currency: [:string, nullable: true],
                    barcode: [:string, nullable: true],
-                   weight_unit: [:string, nullable: true], dimensions_unit: [:string, nullable: true],
                    available_stock: [:number, nullable: true],
                    reserved_quantity: :number, total_on_hand: [:number, nullable: true],
                    preorderable: :boolean, preorder_ships_at: [:string, nullable: true],
                    backorder_limit: [:number, nullable: true],
+                   hs_code: [:string, nullable: true],
+                   country_of_origin: [:string, nullable: true],
+                   customs_description: [:string, nullable: true],
                    deleted_at: [:string, nullable: true],
+                   delivery_profile_id: [:string, nullable: true],
+                   minimum_order_quantity: ['number | null'], order_multiple: ['number | null'],
+                   purchase_unit: [:string, nullable: true, enum: Spree::Variant::PURCHASE_UNITS],
+                   carton_package_type_id: [:string, nullable: true],
+                   carton_weight: [:string, nullable: true],
+                   cartons_per_pallet: ['number | null'],
+                   units_per_pallet: ['number | null'],
                    metadata: 'Record<string, unknown>'
 
+          # The last three override the store serializer's buyer-resolved
+          # values with the variant's OWN: a merchant edits what is stored on
+          # the row, not what some catalog resolves to for a buyer they are not.
           attributes :metadata, :position, :cost_price, :cost_currency,
-                     :barcode, :weight_unit, :dimensions_unit, :backorder_limit,
+                     :barcode, :backorder_limit,
+                     :hs_code, :country_of_origin, :customs_description,
+                     :minimum_order_quantity, :order_multiple, :purchase_unit,
+                     :carton_weight, :cartons_per_pallet,
                      preorder_ships_at: :iso8601, deleted_at: :iso8601,
                      created_at: :iso8601, updated_at: :iso8601
 
@@ -31,8 +48,18 @@ module Spree
             variant.tax_category&.prefixed_id
           end
 
+          # Encoded from the foreign key: loading the carton row just to
+          # re-encode its id is a query per variant on the product listing.
+          attribute :carton_package_type_id do |variant|
+            Spree::PackageType.prefixed_id_for(variant.carton_package_type_id)
+          end
+
+          # How many units a full pallet holds — the far end of the packing
+          # chain, derived so a merchant sees it without doing the arithmetic.
+          attribute :units_per_pallet, &:units_per_pallet
+
           # Physical pool minus already-allocated units. In 5.5 allocated_count
-          # is always 0, so this equals SUM(stock_items.count_on_hand).
+          # is always 0, so this equals SUM(stock_levels.count_on_hand).
           attribute :available_stock do |variant|
             variant.available_stock.to_i if variant.should_track_inventory?
           end
@@ -50,6 +77,21 @@ module Spree
             variant.product&.name
           end
 
+          # How this variant ships — one answer, resolved on the model the same
+          # way the seller is. Writable: on a master product it names how this
+          # seller's row ships; on an owned product the write is a no-op, since
+          # every variant ships as the product does. The dashboard need not
+          # know which.
+          attribute :delivery_profile_id do |variant|
+            variant.resolved_delivery_profile&.prefixed_id
+          end
+
+          one :seller,
+              resource: proc { Spree.api.admin_seller_serializer },
+              if: proc { expand?('seller') } do |variant|
+            variant.resolved_seller
+          end
+
           # Override inherited associations to use admin serializers
           one :primary_media,
               resource: proc { Spree.api.admin_media_serializer },
@@ -67,14 +109,13 @@ module Spree
                resource: proc { Spree.api.admin_price_serializer },
                if: proc { expand?('prices') }
 
-          many :metafields,
-               key: :custom_fields,
+          many :custom_fields,
                resource: proc { Spree.api.admin_custom_field_serializer },
                if: proc { expand?('custom_fields') }
 
-          many :stock_items,
-               resource: proc { Spree.api.admin_stock_item_serializer },
-               if: proc { expand?('stock_items') }
+          many :stock_levels,
+               resource: proc { Spree.api.admin_stock_level_serializer },
+               if: proc { expand?('stock_levels') }
         end
       end
     end

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

@@ -0,0 +1,23 @@
+module Spree
+  module Api
+    module V3
+      # Summary of promotions applied to a Cart or Order (serves the embedded
+      # `discounts` key). Distinct from DiscountSerializer, which serializes
+      # the typed Spree::Discount money rows.
+      class AppliedPromotionSerializer < BaseSerializer
+        typelize name: :string, description: [:string, nullable: true], code: [:string, nullable: true],
+                 amount: [:string, nullable: true], display_amount: [:string, nullable: true], promotion_id: :string
+
+        attribute :promotion_id do |record|
+          record.promotion&.prefixed_id
+        end
+
+        attributes :name, :description, :code
+
+        # Nulled for gated (prices_hidden) guests so an applied discount can't
+        # leak the amount the cart/order totals already withhold.
+        money_attributes :amount, :display_amount
+      end
+    end
+  end
+end

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

@@ -27,6 +27,17 @@ module Spree
           end
         end
 
+        # Plain decimal notation. BigDecimal renders 0.06 as "0.6e-1", which
+        # is what a client would otherwise print beside a unit.
+        #
+        # @param value [BigDecimal, Numeric, nil]
+        # @return [String, nil]
+        def decimal_string(value)
+          return if value.nil?
+
+          BigDecimal(value.to_s).to_s('F')
+        end
+
         # Context accessors
         def current_store
           params[:store]
@@ -83,6 +94,13 @@ module Spree
           end
         end
 
+        # The variant a product leads with in the request's currency: the buy
+        # box winner, else the default variant. Resolved in the same currency
+        # `price_for` prices in, so the two never describe different rows.
+        def featured_variant(product)
+          product.featured_variant(currency: current_currency)
+        end
+
         # Returns price for a variant using full Price List resolution
         # This may return a price from a price list if applicable
         # Memoized per variant to avoid duplicate queries
@@ -102,6 +120,25 @@ module Spree
           )
         end
 
+        # The buyer's effective purchasing rules for a variant — their
+        # catalogs' commercial terms resolved over the variant's own base
+        # rules. Read from the request context the same way price_for does,
+        # so a storefront gets the stepper matching the price it is quoted.
+        #
+        # The resolver is request-scoped, not instance-scoped: Alba builds a
+        # fresh serializer for every element of a collection, so a memo held
+        # here would reload each catalog's override rows once per row on the
+        # page. Resolving without the buyer's company would also answer from
+        # a different agreement than the one pricing the same page.
+        def quantity_rule_for(variant)
+          return Spree::QuantityRule.new if current_store.nil?
+
+          Spree::Current.quantity_rules_resolver_for(
+            company: Spree::Current.standing_company_for(current_user),
+            user: current_user
+          ).call(variant)
+        end
+
         # Returns the base price for a variant without Price List resolution
         # This is the "original" price before any price list discounts
         # Memoized per variant to avoid duplicate queries
@@ -119,9 +156,9 @@ module Spree
           return nil if image.nil?
           return nil unless image.respond_to?(:attached?) && image.attached?
 
-          # Handle Spree::Asset models (like Spree::Image) which have attachment inside
+          # Handle Spree::Media rows, which keep the file in `attachment`
           # vs direct ActiveStorage attachments (like taxon.image)
-          attachment = image.is_a?(Spree::Asset) ? image.attachment : image
+          attachment = image.is_a?(Spree::Media) ? image.attachment : image
           Rails.application.routes.url_helpers.cdn_image_url(attachment)
         end
       end

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

@@ -7,7 +7,16 @@ module Spree
         typelize number: :string, current_step: :string, completed_steps: 'string[]', token: :string, email: [:string, nullable: true],
                  customer_note: [:string, nullable: true], market_id: [:string, nullable: true], channel_id: [:string, nullable: true],
                  currency: :string, locale: [:string, nullable: true], total_quantity: :number,
-                 requirements: 'Array<{step: string, field: string, message: string}>',
+                 coupon_code: [:string, nullable: true],
+                 preferred_stock_location_id: [:string, nullable: true],
+                 company_id: [:string, nullable: true], company_name: [:string, nullable: true],
+                 po_number: [:string, nullable: true], po_number_required: :boolean,
+                 po_document_filename: [:string, nullable: true],
+                 po_document_byte_size: ['number | null'],
+                 order_minimum: ['number | null'], order_minimum_shortfall: ['number | null'],
+                 below_order_minimum: ['boolean | null'],
+                 freight_summary: [:FreightSummary, nullable: true],
+                 requirements: 'Array<{step: string, field: string, code: string, message: string}>',
                  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],
@@ -15,21 +24,17 @@ 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],
                  shipping_eq_billing_address: :boolean,
-                 warnings: 'Array<{code: string, message: string, line_item_id?: string, variant_id?: string}>',
+                 warnings: 'Array<{code: string, message: string, line_item_id?: string, variant_id?: string, item_index?: number}>',
                  billing_address: { nullable: true }, shipping_address: { nullable: true },
                  gift_card: { nullable: true }, market: { nullable: true }
 
-        # Override ID to use cart_ prefix
-        attribute :id do |order|
-          "cart_#{Spree::PrefixedId::SQIDS.encode([order.id])}"
-        end
-
         attribute :market_id do |order|
           order.market&.prefixed_id
         end
@@ -41,8 +46,40 @@ module Spree
           order.channel&.prefixed_id
         end
 
-        attributes :number, :token, :email, :customer_note,
-                   :currency, :locale, :total_quantity, :warnings
+        # Pickup selection — mirrors the writable param on cart update.
+        attribute :preferred_stock_location_id do |cart|
+          cart.preferred_stock_location&.prefixed_id
+        end
+
+        # Which company node the purchase is for — mirrors the writable
+        # `company_id` param. Read from the column, never re-resolved.
+        attribute :company_id do |cart|
+          cart.company&.prefixed_id
+        end
+
+        attribute :company_name do |cart|
+          cart.company&.name
+        end
+
+        # The buyer's own purchase-order reference, and whether their company
+        # demands one — the storefront marks the field required from this
+        # rather than fetching the company to ask.
+        attribute :po_number_required do |cart|
+          cart.po_number_required?
+        end
+
+        attribute :po_document_filename do |cart|
+          cart.po_document.blob&.filename&.to_s if cart.po_document.attached?
+        end
+
+        attribute :po_document_byte_size do |cart|
+          cart.po_document.blob&.byte_size if cart.po_document.attached?
+        end
+
+        # @deprecated `number` mirrors `id` (carts have no order-style
+        #   number) — kept one release for 5.x clients; removed in 6.1.
+        attributes :number, :token, :email, :customer_note, :po_number,
+                   :currency, :locale, :total_quantity, :warnings, :coupon_code
 
         # Nulled for gated (prices_hidden) guests so the cart can't leak the
         # prices that product/variant serializers already withhold.
@@ -53,7 +90,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]
@@ -75,15 +113,55 @@ module Spree
           order.completed_checkout_steps
         end
 
+        # The order-minimum requirement names both amounts in its message, so
+        # it is dropped rather than redacted for a gated guest: a requirement
+        # with its numbers stripped tells them nothing they can act on.
         attribute :requirements do |order|
-          Spree::Checkout::Requirements.new(order).call
+          requirements = Spree::Checkout::Requirements.new(order).call
+          next requirements unless params[:hide_prices]
+
+          requirements.reject { |requirement| requirement[:code] == 'order_minimum_not_met' }
+        end
+
+        # The order minimum in force for this buyer, or nil when their
+        # agreements state none. Exposed alongside the shortfall so a
+        # storefront can render "$180 to reach the $500 minimum" without
+        # doing the arithmetic or knowing where the number came from.
+        #
+        # Gated with the rest of the price surface: a threshold and a
+        # shortfall are amounts, and a storefront that hides prices from
+        # guests must not hand them "$180 short of $500" instead.
+        attribute :order_minimum do |order|
+          order.order_minimum_amount&.to_f unless params[:hide_prices]
         end
 
+        attribute :order_minimum_shortfall do |order|
+          order.order_minimum_shortfall&.to_f unless params[:hide_prices]
+        end
+
+        attribute :below_order_minimum do |order|
+          order.below_order_minimum? unless params[:hide_prices]
+        end
+
+        # The shipment as a freight forwarder reads it: cartons, pallets,
+        # cubic meters, gross weight. Null for anything the store never
+        # measured that way, which is every retail cart.
+        #
+        # The totals are logistics rather than amounts, so they survive a
+        # storefront that hides prices; the per-line SKU and product name do
+        # not, being the catalog identity such a storefront exists to
+        # withhold.
+        one :freight_summary, resource: proc { Spree.api.freight_summary_serializer }
+
         attribute :shipping_eq_billing_address do |order|
           order.shipping_eq_billing_address?
         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). Storefronts
+        # group and label these themselves — cross-border duty in particular
+        # has to be shown broken out rather than folded into a total.
+        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 }