@spree/docs 0.1.219 → 0.1.220

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/package.json

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