Multi-Address Checkout

Paid pluginsize Mplanned, not built

Indicative price, not an offer: $99–199/year

Generated from docs/plan/paid/multi-address-checkout/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

Some orders ship to multiple destinations (e.g., corporate gifts to different addresses). This paid feature allows different items in one order to ship to different addresses.

The problem

I’m placing an order with 5 gifts, each going to a different friend. Currently, all items must ship to one address. I need to assign each item a destination address before checkout.

What it does

• Order line item expansion: each OrderItem can have a ship_to_address (optional; if absent, uses order-level shipping address)
• Checkout flow: after item selection, before totals, show address assignment screen (optional, merchant-configured)
• Shipping cost per destination: system groups items by address and calculates shipping separately for each group
• Tax by destination: calculate tax based on each destination address (if applicable per region)
• Packing slip generation: per-destination packing slip (or per-item, with destination label)
• Limitation: cap at 3–5 different destinations per order (to avoid complex logistics)

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• Warehouse picking and packing complexity — core tracks which items go where; fulfillment system (WMS) owns the picking. Module just stores the intent.
• Carrier splitting — if destination 1 and 2 are served by different carriers, that’s merchant’s problem. Module routes to fulfillment system; fulfillment chooses carriers.

Data model

Add to OrderItem: ship_to_address (Address object, optional). If absent, use Order.shipping_address. Migration: existing orders have all items shipping to order-level address (backward compatible).

API

• POST /api/orders — checkout payload includes items with optional ship_to_address per line
• GET /api/orders/{id}/shipping-groups — return items grouped by destination address with shipping cost per group

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Order detail view shows a ‘Shipping Destinations’ section: a table with ‘Item | Destination Address | Shipping Cost | Total’. Admin can edit ship_to_address if order is still pending.

The seam — why this is paid

Core owns Order model and shipping calculation logic. Paid module owns per-item address assignment and multi-destination shipping totals.

Edge-case operational feature. Uncommon for typical retail. Requires MSI/warehouse support to be useful. Bundled as a paid feature extension.

Dependencies

• structured-address-model — need structured addresses per line
• shopping-cart → order placement

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• Order with 3 items: item 1 ship to Berlin, item 2 to Hamburg, item 3 to Berlin
• Shipping calculated per group: Berlin group €5, Hamburg group €8, total shipping €13 (not €5 * 3 = €15)
• Packing slip generated per destination: slip 1 has items 1 + 3 (Berlin), slip 2 has item 2 (Hamburg)
• Tax calculated per destination: item 1 and 3 use Berlin tax rules, item 2 uses Hamburg tax rules
• Cap: trying to assign 6 different addresses → rejected (max 5), with error code ‘checkout.too_many_destinations’
• Merchant can edit destination after order placed (before fulfillment); change is audit-logged

Risks

Shipping cost explosion: if each item has a different address, shipping totals can be nonsensical (€1 item + €50 shipping to each destination = expensive gift). Merchants must validate business logic. Packing slip chaos: fulfillment team receives per-destination packing slips; if the system sends them all at once, team must sort. A fulfillment WMS should split orders into shipments automatically. Tax complexity: calculating tax per destination is non-trivial if tax rules are complex; a mistake exposes the merchant to audit. Validation must be thorough.

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.