@spree/docs 0.1.219 → 0.1.221

package/dist/api-reference/store.yaml

@@ -2010,8 +2010,8 @@ paths:
                 coupon_code:
                 item_total: '0.0'
                 display_item_total: "$0.00"
-                adjustment_total: '0.0'
-                display_adjustment_total: "$0.00"
+                adjustment_total: '17.0'
+                display_adjustment_total: "$17.00"
                 discount_total: '0.0'
                 display_discount_total: "$0.00"
                 tax_total: '0.0'
@@ -2020,16 +2020,16 @@ paths:
                 display_included_tax_total: "$0.00"
                 additional_tax_total: '0.0'
                 display_additional_tax_total: "$0.00"
-                total: '0.0'
-                display_total: "$0.00"
+                total: '17.0'
+                display_total: "$17.00"
                 gift_card_total: '0.0'
                 display_gift_card_total: "$0.00"
-                amount_due: '0.0'
-                display_amount_due: "$0.00"
+                amount_due: '17.0'
+                display_amount_due: "$17.00"
                 delivery_total: '0.0'
                 display_delivery_total: "$0.00"
-                fee_total: '0.0'
-                display_fee_total: "$0.00"
+                fee_total: '17.0'
+                display_fee_total: "$17.00"
                 store_credit_total: '0.0'
                 display_store_credit_total: "$0.00"
                 covered_by_store_credit: false
@@ -2044,13 +2044,31 @@ paths:
                   step: address
                   field: email
                   message: Email address is required
+                - code: payment_required
+                  step: payment
+                  field: payment
+                  message: Add a payment method
                 order_minimum:
                 order_minimum_shortfall:
                 below_order_minimum: false
                 freight_summary:
                 shipping_eq_billing_address: true
                 discounts: []
-                fees: []
+                fees:
+                - id: fee_UkLWZg9DAJ
+                  label: Gift wrapping
+                  kind: gift_wrap
+                  line_item_id:
+                  fulfillment_id:
+                  amount: '5.0'
+                  display_amount: "$5.00"
+                - id: fee_gbHJdmfrXB
+                  label: Import duty
+                  kind: duty
+                  line_item_id:
+                  fulfillment_id:
+                  amount: '12.0'
+                  display_amount: "$12.00"
                 items: []
                 fulfillments: []
                 payments: []
@@ -5665,8 +5683,8 @@ paths:
                 completed_at: '2026-01-15T12:00:00.000Z'
                 item_total: '10.0'
                 display_item_total: "$10.00"
-                adjustment_total: '0.0'
-                display_adjustment_total: "$0.00"
+                adjustment_total: '12.0'
+                display_adjustment_total: "$12.00"
                 discount_total: '0.0'
                 display_discount_total: "$0.00"
                 tax_total: '0.0'
@@ -5675,21 +5693,28 @@ paths:
                 display_included_tax_total: "$0.00"
                 additional_tax_total: '0.0'
                 display_additional_tax_total: "$0.00"
-                total: '110.0'
-                display_total: "$110.00"
+                total: '122.0'
+                display_total: "$122.00"
                 gift_card_total: '0.0'
                 display_gift_card_total: "$0.00"
-                amount_due: '110.0'
-                display_amount_due: "$110.00"
+                amount_due: '122.0'
+                display_amount_due: "$122.00"
                 delivery_total: '100.0'
                 display_delivery_total: "$100.00"
-                fee_total: '0.0'
-                display_fee_total: "$0.00"
+                fee_total: '12.0'
+                display_fee_total: "$12.00"
                 store_credit_total: '0.0'
                 display_store_credit_total: "$0.00"
                 covered_by_store_credit: false
                 discounts: []
-                fees: []
+                fees:
+                - id: fee_UkLWZg9DAJ
+                  label: Import duty
+                  kind: duty
+                  line_item_id:
+                  fulfillment_id:
+                  amount: '12.0'
+                  display_amount: "$12.00"
                 items:
                 - id: li_UkLWZg9DAJ
                   variant_id: variant_UkLWZg9DAJ
@@ -12395,7 +12420,17 @@ components:
         number:
           type: string
         status:
-          type: string
+          anyOf:
+          - type: string
+            enum:
+            - open
+            - approved
+            - resolved
+            - denied
+            - canceled
+          - type: string
+          description: The values listed are the built-in ones; extensions may add
+            more.
         resolution:
           type: string
           nullable: true
@@ -12508,6 +12543,11 @@ components:
           type: string
         status:
           type: string
+          enum:
+          - pending
+          - accepted
+          - revoked
+          - expired
       required:
       - id
       - email
@@ -12542,6 +12582,9 @@ components:
           type: string
         kind:
           type: string
+          enum:
+          - company
+          - division
         po_number_required:
           type: boolean
         parent_id:
@@ -12745,8 +12788,20 @@ components:
           type: string
         kind:
           type: string
+          enum:
+          - access
+          - erasure
         status:
-          type: string
+          anyOf:
+          - type: string
+            enum:
+            - pending
+            - processing
+            - completed
+            - failed
+          - type: string
+          description: The values listed are the built-in ones; extensions may add
+            more.
         requested_at:
           type: string
           nullable: true
@@ -12770,8 +12825,20 @@ components:
           type: string
         kind:
           type: string
+          enum:
+          - access
+          - erasure
         status:
-          type: string
+          anyOf:
+          - type: string
+            enum:
+            - pending
+            - processing
+            - completed
+            - failed
+          - type: string
+          description: The values listed are the built-in ones; extensions may add
+            more.
         requested_at:
           type: string
           nullable: true
@@ -12914,6 +12981,16 @@ components:
           nullable: true
         status:
           type: string
+          enum:
+          - pending
+          - pre_transit
+          - in_transit
+          - out_for_delivery
+          - available_for_pickup
+          - delivered
+          - return_to_sender
+          - failure
+          - unknown
         tracking_url:
           type: string
           nullable: true
@@ -12941,6 +13018,10 @@ components:
           type: string
         member_type:
           type: string
+          enum:
+          - country
+          - state
+          - postal_code
         country_code:
           type: string
           nullable: true
@@ -13054,6 +13135,9 @@ components:
           type: string
         kind:
           type: string
+          enum:
+          - promotion
+          - manual
         code:
           type: string
           nullable: true
@@ -13099,7 +13183,19 @@ components:
         label:
           type: string
         kind:
-          type: string
+          anyOf:
+          - type: string
+            enum:
+            - surcharge
+            - handling
+            - gift_wrap
+            - cod
+            - payment
+            - duty
+          - type: string
+          description: What sort of charge this is. `duty` is a customs duty on a
+            cross-border order and is not taxed; the other kinds are. Extensions may
+            register further kinds.
         line_item_id:
           type: string
           nullable: true
@@ -13203,9 +13299,23 @@ components:
           type: string
           nullable: true
         status:
-          type: string
+          anyOf:
+          - type: string
+            enum:
+            - unfulfilled
+            - fulfilled
+            - delivered
+            - canceled
+          - type: string
+          description: The values listed are the built-in ones; extensions may add
+            more.
         fulfillment_type:
           type: string
+          enum:
+          - shipping
+          - digital
+          - pickup
+          - pickup_point
         fulfilled_at:
           type: string
           nullable: true
@@ -13307,7 +13417,17 @@ components:
         code:
           type: string
         status:
-          type: string
+          anyOf:
+          - type: string
+            enum:
+            - active
+            - partially_redeemed
+            - redeemed
+            - canceled
+            - expired
+          - type: string
+          description: The values listed are the built-in ones; extensions may add
+            more.
         currency:
           type: string
         amount:
@@ -13370,7 +13490,14 @@ components:
         updated_at:
           type: string
         status:
-          type: string
+          anyOf:
+          - type: string
+            enum:
+            - pending
+            - accepted
+          - type: string
+          description: The values listed are the built-in ones; extensions may add
+            more.
         resource_type:
           type: string
           nullable: true
@@ -13608,6 +13735,10 @@ components:
           type: string
         media_type:
           type: string
+          enum:
+          - image
+          - video
+          - external_video
         position:
           type: number
           nullable: true
@@ -13647,6 +13778,10 @@ components:
           nullable: true
         media_type:
           type: string
+          enum:
+          - image
+          - video
+          - external_video
         focal_point_x:
           type: number
           nullable: true
@@ -13752,6 +13887,10 @@ components:
           type: number
         kind:
           type: string
+          enum:
+          - dropdown
+          - color_swatch
+          - buttons
       required:
       - id
       - name
@@ -13820,9 +13959,28 @@ components:
         fulfillment_status:
           type: string
           nullable: true
+          enum:
+          - backorder
+          - canceled
+          - partial
+          - unfulfilled
+          - fulfilled
+          - delivered
+          - pending
+          - ready
+          - shipped
         payment_status:
           type: string
           nullable: true
+          enum:
+          - none
+          - authorized
+          - partially_paid
+          - paid
+          - partially_refunded
+          - refunded
+          - overcharged
+          - voided
         completed_at:
           type: string
           nullable: true
@@ -13908,9 +14066,28 @@ components:
         fulfillment_status:
           type: string
           nullable: true
+          enum:
+          - backorder
+          - canceled
+          - partial
+          - unfulfilled
+          - fulfilled
+          - delivered
+          - pending
+          - ready
+          - shipped
         payment_status:
           type: string
           nullable: true
+          enum:
+          - none
+          - authorized
+          - partially_paid
+          - paid
+          - partially_refunded
+          - refunded
+          - overcharged
+          - voided
         completed_at:
           type: string
           nullable: true
@@ -14093,6 +14270,9 @@ components:
           nullable: true
         type:
           type: string
+          description: '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:
           type: boolean
         source_required:
@@ -14118,7 +14298,19 @@ components:
         number:
           type: string
         status:
-          type: string
+          anyOf:
+          - type: string
+            enum:
+            - checkout
+            - processing
+            - pending
+            - completed
+            - failed
+            - void
+            - invalid
+          - type: string
+          description: The values listed are the built-in ones; extensions may add
+            more.
         amount:
           type: string
           nullable: true
@@ -14162,7 +14354,18 @@ components:
         id:
           type: string
         status:
-          type: string
+          anyOf:
+          - type: string
+            enum:
+            - pending
+            - processing
+            - completed
+            - failed
+            - canceled
+            - expired
+          - type: string
+          description: The values listed are the built-in ones; extensions may add
+            more.
         currency:
           type: string
         external_id:
@@ -14209,7 +14412,18 @@ components:
         id:
           type: string
         status:
-          type: string
+          anyOf:
+          - type: string
+            enum:
+            - pending
+            - processing
+            - completed
+            - failed
+            - canceled
+            - expired
+          - type: string
+          description: The values listed are the built-in ones; extensions may add
+            more.
         external_id:
           type: string
           nullable: true
@@ -14426,6 +14640,10 @@ components:
           type: string
         kind:
           type: string
+          enum:
+          - dropdown
+          - color_swatch
+          - buttons
         options:
           type: array
           items:
@@ -14787,7 +15005,17 @@ components:
         number:
           type: string
         status:
-          type: string
+          anyOf:
+          - type: string
+            enum:
+            - requested
+            - approved
+            - received
+            - refunded
+            - canceled
+          - type: string
+          description: The values listed are the built-in ones; extensions may add
+            more.
         order_id:
           type: string
           nullable: true
@@ -14872,8 +15100,19 @@ components:
           type: string
         source:
           type: string
+          enum:
+          - purchased
+          - uploaded
         status:
-          type: string
+          anyOf:
+          - type: string
+            enum:
+            - purchased
+            - refund_requested
+            - refunded
+          - type: string
+          description: The values listed are the built-in ones; extensions may add
+            more.
         carrier:
           type: string
           nullable: true
@@ -14908,6 +15147,9 @@ components:
           type: string
         owner_type:
           type: string
+          enum:
+          - Spree::Fulfillment
+          - Spree::Return
         cost:
           type: string
         display_cost:
@@ -15045,6 +15287,8 @@ components:
           type: string
         kind:
           type: string
+          description: 'Tax identifier kind, keyed to a registered validator. Built-in:
+            eu_vat. Extensions may register more.'
         value:
           type: string
       required:
@@ -15137,14 +15381,27 @@ components:
           nullable: true
         weight_unit:
           type: string
+          enum:
+          - g
+          - kg
+          - lb
+          - oz
         dimensions_unit:
           type: string
+          enum:
+          - mm
+          - cm
+          - in
+          - ft
         minimum_order_quantity:
           type: number
         order_multiple:
           type: number
         purchase_unit:
           type: string
+          enum:
+          - unit
+          - carton
         units_per_carton:
           type: number
           nullable: true

package/dist/developer/core-concepts/delivery-setup.md

@@ -118,6 +118,77 @@ A method is priced one of two ways, and the choice is per method:
 A carrier-priced method returns one option per service, so a single "Carrier
 rates" method can offer Ground, 2-Day and Overnight as separate choices.
 
+## Packaging
+
+Every quote needs to know what the goods travel in. A carrier charges by
+dimensional weight as well as actual weight, so the size of the box matters to
+the price, and the empty box's own weight has to be added to what it holds —
+otherwise every parcel is quoted light.
+
+Package types are that vocabulary: the box parcels ship in, and for wholesale,
+the cartons products are packed into and the pallets or containers an order
+leaves on.
+
+```typescript Admin SDK
+await adminClient.packageTypes.create({
+  name: 'Standard mailer',
+  kind: 'box',
+  length: 30, width: 20, height: 15, dimensions_unit: 'cm',
+  weight: 0.4, weight_unit: 'kg',
+  default: true,
+})
+```
+
+One row is marked `default`, and that is the box quotes are built on. Marking
+another one default demotes the first, so there is never more than one.
+
+Measurements are optional individually, which is how a merchant records what
+they know. A box with no dimensions still contributes its weight; a box with
+nothing measured contributes nothing, and dimensional pricing has nothing to
+work from.
+
+> **NOTE:** Deleting the default box is refused, and so is switching its flag off when
+> nothing else would take it. Both would leave quotes with no size and no tare,
+> which under-prices bulky parcels silently rather than failing.
+
+### On a marketplace
+
+A seller packs their own goods, in their own boxes, from their own warehouse.
+So packaging has an owner: rows created by the operator are the marketplace's,
+and each seller has their own.
+
+A parcel is quoted with the box belonging to whoever's warehouse it left,
+falling back to the marketplace's when a seller has not recorded one. Sellers
+manage theirs through the Seller API, and can also pack products into the
+marketplace's cartons — those they read but cannot change.
+
+```typescript Seller SDK
+// Their own packaging — what the seller panel's settings page lists.
+const { data: mine } = await sellerClient.packageTypes.list({ owner: 'mine' })
+
+// Their own plus the marketplace's, which is what a carton picker wants.
+const { data: available } = await sellerClient.packageTypes.list()
+
+available.forEach((row) => {
+  row.name
+  row.editable   // false on the marketplace's own rows
+  row.default    // this seller's default box
+})
+```
+
+A seller's settings page asks for `owner: 'mine'`. A list mixing both owners
+reads as "packaging is configured" while the seller has recorded nothing of
+their own, which makes the shipping-box requirement look broken rather than
+outstanding. Where a seller genuinely benefits from the marketplace's rows —
+choosing the carton a product is packed into — the unfiltered list is what
+the picker reads.
+
+Because the fallback keeps checkout working, a seller who never opens the page
+would quietly ship with someone else's measurements. The **shipping box**
+onboarding requirement is what asks them for it: it is satisfied by a default
+box of their own with all three dimensions and a weight recorded. See
+[sellers](sellers.md#onboarding-requirements).
+
 ## Related
 
 - [Fulfillments](fulfillments.md) — what happens to the parcel afterwards

package/dist/developer/core-concepts/sellers.md

@@ -85,7 +85,7 @@ Requirements come in three flavours, which is what lets one mechanism cover very
 | **Attested** | The seller confirms something — accepting terms |
 | **Verified** | The seller submits something and the marketplace rules on it — a document, an operator review |
 
-Shipped out of the box: accepting terms, completing the profile, a billing address, a returns address, and a minimum number of products. Also available are generic document upload, attestation, operator review, and required custom fields.
+Shipped out of the box: accepting terms, completing the profile, a billing address, a returns address, a way to ship, the box they ship in, and a minimum number of products. Also available are generic document upload, attestation, operator review, and required custom fields.
 
 A seller sees their checklist and its progress:
 
@@ -197,7 +197,7 @@ await sellerClient.orders.fulfillments.fulfill(orderId, fulfillmentId, {
 })
 ```
 
-Sellers can manage their profile, invite their own team, list and submit products, see and fulfil their orders, manage their stock locations, and work through onboarding. They cannot see other sellers, the marketplace's own catalog, or anything belonging to the store at large.
+Sellers can manage their profile, invite their own team, list and submit products, see and fulfil their orders, manage their stock locations, delivery methods and packaging, and work through onboarding. They cannot see other sellers, the marketplace's own catalog, or anything belonging to the store at large.
 
 What a seller's staff may do is governed by [roles](staff-roles.md) owned by the seller — the same permission system as the back office, with a narrower set of keys, so a seller role can never reach store settings.
 
@@ -206,5 +206,6 @@ What a seller's staff may do is governed by [roles](staff-roles.md) owned by the
 - [Commissions](commissions.md) — rates, rules, and what the marketplace charges
 - [Products](products.md#seller-submissions) — the listing review flow
 - [Orders](orders.md) — orders and their statuses
+- [Delivery setup](delivery-setup.md#on-a-marketplace) — how a seller's goods ship, and what they ship in
 - [Staff & Roles](staff-roles.md) — how seller teams are governed
 - [Seller API](../../api-reference/seller-api/introduction.md) — the full endpoint reference

package/dist/developer/sdk/store/cart-checkout.md

@@ -77,6 +77,27 @@ const cart = await client.carts.giftCards.apply(cartId, 'GC-ABCD-1234', options)
 await client.carts.giftCards.remove(cartId, 'gc_abc123', options);
 ```
 
+### Fees and Duties
+
+A cart may carry charges that are neither a product price nor tax: gift wrapping, a handling charge, a cash-on-delivery surcharge, or an import duty on a cross-border order. Each is a [fee](../../core-concepts/fees.md) on the cart, and the storefront should show every one of them before the customer pays.
+
+```typescript
+const cart = await client.carts.get(cartId, options);
+
+cart.fees.forEach((fee) => {
+  fee.label;          // "Import duty"
+  fee.kind;           // "duty"
+  fee.display_amount; // "$12.00"
+  fee.line_item_id;   // set when the fee is for one item, otherwise null
+});
+
+cart.display_fee_total; // "$17.00"
+```
+
+`kind` is one of `surcharge`, `handling`, `gift_wrap`, `cod`, `payment` or `duty`. Fees are already part of `total`, so list them as their own lines between the subtotal and the total; never add them on top. A `duty` fee is a customs charge and is not taxed, which is why it is worth showing under its own label rather than folding it into a generic "fees" line.
+
+Fees are written by the merchant or by an integration, never by the customer; there is no Store API endpoint to create one.
+
 ## Checkout
 
 ### Update Cart
@@ -136,10 +157,18 @@ await client.carts.storeCredits.apply(cartId, 25.00, options);
 await client.carts.storeCredits.remove(cartId, options);
 ```
 
-The cart/order response includes store credit and gift card totals:
+### Totals
+
+The cart and order responses break the amount the customer pays into these totals. Each has a raw string value and a `display_` twin formatted in the cart's currency.
 
-- `store_credit_total` / `display_store_credit_total` — total store credit applied
-- `gift_card_total` / `display_gift_card_total` — total gift card value applied
+- `item_total` — the products, before anything else
+- `delivery_total` — the selected delivery rates
+- `discount_total` — promotions and discount codes, as a negative amount
+- `fee_total` — every [fee](#fees-and-duties) on the cart, duties included
+- `tax_total` — tax on items, delivery and taxable fees
+- `total` — what the order costs: items, delivery, fees and tax, less discounts
+- `store_credit_total` / `gift_card_total` — store credit or gift card value applied against the total
+- `amount_due` — what is left to pay after store credit and gift cards
 - `covered_by_store_credit` — boolean, whether the order is fully covered by store credit
 - `gift_card` — associated gift card (if applicable)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spree/docs",
-  "version": "0.1.219",
+  "version": "0.1.221",
   "description": "Spree Commerce developer documentation for AI agents and local reference",
   "type": "module",
   "license": "CC-BY-4.0",