Wine2You-Order-API-Taxonomy

Wine2You — Order API Taxonomy

Version: 2.0 · Owner: Wine2You Platform · Status: model update (supersedes v1.0) Scope: how an order is captured, priced across a selected offer, fulfilled (estate-first or indirect), documented, settled and reported. Companion documents: PIM Product API Taxonomy, Partner Onboarding.

One sentence. An order is the API representation of the flash sell-buy-sell: at the instant a consumer buys, Wine2You purchases the wine from the offer that was selected (at that originator's seller_price) and sells it to the consumer (at the destination landed price) — atomically. Which offer was selected, and who fulfils it, is now an explicit part of the order.

1. Overview & design principles

2. Resource map

3. The order object taxonomy

4. Order lifecycle state machine

States (enum):

draft (cart) → placed → paid → confirmed → sourced → reserved
   → fulfilled → in_transit → delivered → settled
Terminal / branch: cancelled, failed, refunded, returned

Transitions:

sourced and reserved are new — they make multi-provider routing explicit rather than assumed.

5. Sourcing & routing logic (estate-first, then other inventories)

Routing runs at quote-calculate (preview) and confirmed → sourced (commit). Per line:

1. Estate direct (priority 1). If the wine's estate is an Originator on W2Y and its offer is active with sufficient atp → select estate offer. (Estate sales are preferred.)
2. Other inventories (priority 2). Otherwise (or if estate ATP is short) select another active offer whose originator permits the transaction: permissions (allowed countries / named sellers / default any) + network_shareable + destination eligibility must pass. This is indirect sourcing, gated by feed-curation.
3. Split. If no single offer covers the quantity, allocate across offers (cheapest/compliant first, or explicit policy) → each allocation becomes its own sourcing.source[] entry and its own fulfilment leg.

sourcing object:

{ "priority": "estate_first",
  "split_reason": "estate_atp_short",      // or "multi_originator_policy"
  "source": [
    { "offer_id": "off_estate_1", "originator_id": "partner_estate_x",
      "qty": 4, "p2b": 18.00, "incoterm": "FCA", "fulfiller_id": "partner_estate_x" },
    { "offer_id": "off_importer_1", "originator_id": "partner_importer_ch",
      "qty": 2, "p2b": 20.50, "incoterm": "DAP", "fulfiller_id": "partner_3pl_ch" } ] }

Each source's p2b = that offer's seller_price → the line's P_B2B in the waterfall. A line split across offers carries one p2b per source.

6. Fulfilment roles & split legs

• Fulfiller = the partner who picks/packs/ships. By default the stock owner fulfils their leg; an originator that enables fulfills_orders ships its own; a 3PL/Fulfiller partner can ship on behalf of a source.
• Split fulfilment: one order → N fulfilments, each bound to location_id + fulfiller_id + its items. Each has its own pickup, carrier, tracking and delivery scan. (Medusa v2: an order → many Fulfillment.)
• Reservation: at reserved, a ReservationItem per source/location holds stock; on fulfilment creation it decrements stocked_quantity; on cancel it releases. This is the back-to-back dropship primitive.
• Seller vs Fulfiller: the Seller owns the consumer relationship and price; the Fulfiller executes physical delivery for the source it holds. One partner may be both (an Estate = Originator + Fulfiller + Seller).

7. Pricing & financial taxonomy

The landed-price waterfall (P_final, per destination) — P_B2B now comes from the selected offer:

P_final = P_B2B + R_Recruiter + M_Curator + F_Platform + C_Freight + E_Excise + V_VAT

financial_breakdown (what the consumer pays):

{ "currency": "NOK",
  "lines": [
    { "component": "P_B2B", "amount": 18.00, "offer_id": "off_estate_1" },
    { "component": "M_Curator", "amount": 4.20 },
    { "component": "F_Platform", "amount": 1.50 },
    { "component": "C_Freight", "amount": 6.00 },
    { "component": "E_Excise", "amount": 12.40 },
    { "component": "V_VAT", "amount": 9.48 } ],
  "total": 51.58 }

settlement_split (who gets what — now per partner, since sources/sellers/fulfillers differ):

{ "currency": "EUR",
  "parties": [
    { "partner_id": "partner_estate_x", "role": "originator", "amount": 72.00, "basis": "p2b × 4" },
    { "partner_id": "partner_importer_ch", "role": "originator", "amount": 41.00, "basis": "p2b × 2" },
    { "partner_id": "partner_curator_ch", "role": "seller", "amount": 25.20, "basis": "M_Curator" },
    { "partner_id": "partner_3pl_ch", "role": "fulfiller", "amount": 6.00, "basis": "fulfilment fee" } ],
  "platform_fee": 1.50,
  "escrowed_taxes": { "excise": 12.40, "vat": 9.48 } }

Currency & rounding: consumer charged in destination currency; internal ledger in EUR. Round half-up to the destination's minor unit; tax components rounded per line, summed (never rounded twice).

8. Documents taxonomy

All generated from the same order data; a split order emits per-source originator docs and per-leg labels.

9. Compliance & reporting taxonomy

Delivery-register record (per delivery): date · consignee · delivery_address · product_description · excise_category_code · commodity_code (ch.22) · units_delivered · unit_capacity_litres · abv.

• Excise: declared/paid in the destination monthly via the local fiscal representative.
• VAT: Union OSS or local registration per destination.
• Non-EU (Norway): separate VAT + excise; prepaid import MVA (25%), Alkoholavgift (V × ABV/100), packaging fees; TVINN pre-clearance; Vipps age/identity verification.
• Per-order volume caps: e.g. 90 L still / 60 L sparkling per consumer (destination-dependent).
• Split orders: filings aggregate across legs into one destination declaration; each leg still carries its originator for the transport document.

10. Settlement & payout taxonomy

• Trigger: payout released at shipment date + X days (per leg; earliest leg can gate). Complaint window 7 days after delivery.
• Payout states: pending → eligible → paid → (clawed_back), per party (originator, seller, fulfiller).
• VAT on originator→platform invoice: cross-border → reverse charge; consumer in originator's own country → originator invoices with its own national VAT.

11. Webhooks & events taxonomy (proposed)

At-least-once, signed, Idempotency-Key = event id; exponential backoff + dead-letter queue.

12. Proposed core endpoints

13. Worked example — estate-first, then split for the short 2 bottles

Quote request:

POST /v1/orders/quote-calculate
{ "destination_country": "NO",
  "seller": "partner_curator_ch",
  "lines": [{ "sku": "CAN-BAR-2019-750", "qty": 6, "box_units": 6 }] }

Quote response (routing preview):

{ "currency": "NOK",
  "sourcing": {
    "priority": "estate_first", "split_reason": "estate_atp_short",
    "source": [
      { "offer_id": "off_estate_1", "originator_id": "partner_estate_x", "qty": 4, "p2b": 18.00 },
      { "offer_id": "off_importer_1", "originator_id": "partner_importer_ch", "qty": 2, "p2b": 20.50 } ] },
  "financial_breakdown": { "lines": [
      { "component": "P_B2B", "amount": 18.00, "offer_id": "off_estate_1" },
      { "component": "M_Curator", "amount": 4.20 },
      { "component": "F_Platform", "amount": 1.50 },
      { "component": "C_Freight", "amount": 6.00 },
      { "component": "E_Excise", "amount": 12.40 },
      { "component": "V_VAT", "amount": 9.48 } ],
    "total": 51.58 },
  "settlement_split": { "parties": [
      { "partner_id": "partner_estate_x", "role": "originator", "amount": 72.00 },
      { "partner_id": "partner_importer_ch", "role": "originator", "amount": 41.00 },
      { "partner_id": "partner_curator_ch", "role": "seller", "amount": 25.20 } ],
    "platform_fee": 1.50 } }

Lifecycle (illustrative):

14. Best-practice notes

• Idempotency keys on create/pay/pickup — checkout retries and carrier webhooks never double-create/double-pay.
• Why sourced is explicit: estate-first vs indirect is a decision with reasons, not an assumption. Recording it makes split/routing auditable and lets ops re-run routing when a source fails.
• Per-party settlement: once one order can involve several originators, a fulfiller and a seller, a single supplier_payout field is wrong — payouts must be modelled per party from the start.
• Why the flash must be atomic: model as reserve_source_stock → charge_consumer → commit_buy → commit_sell, with compensation unwinding any completed leg. With multiple sources, each buy leg compensates independently.
• Reconciliation: nightly compare orders ↔ sourcing ↔ settlement ↔ compliance; a paid order with no filed duty, or a filed duty with no paid order, is an ops alert.