One basket, many platforms, one order

Documents 04 and 05 explained how QuickCart finds the best price, stock and ETA for a single product across five platforms. This document explains what happens when a shopper wants several products at once — and those products live on different platforms. The answer is the piece that turns QuickCart from a comparison tool into a marketplace: a cross-platform cart, one internal order, and an orchestrator that procures and delivers everything under a single QuickCart receipt.

The model: QuickCart is the merchant of record

A price-comparison app stops at "Blinkit is cheapest — tap to open Blinkit." QuickCart goes further: the shopper transacts once, with QuickCart. Behind that single order, QuickCart procures each line item from whichever platform is cheapest and in stock, then delivers the whole basket. The shopper never creates five accounts, pays five times, or tracks five parcels.

Procurement of any given line happens in one of two modes — the same two modes introduced in the Architecture document (§9, Payments):

Building a cross-platform basket

A QuickCart cart is a flat list of lines. Every line references a canonical SKU (the platform-independent product from the Catalogue, Doc 03 §6) plus a chosen sourceId. By default the source is the ranked winner from the Price Engine (Doc 05); the shopper can override it ("I'd rather get the butter from Zepto — it's faster"). Because lines carry their own source, one cart naturally spans multiple platforms.

{
  "cartId": "crt_9f2a1c",
  "userId": "usr_512",
  "pincode": "560103",
  "lines": [
    {
      "lineId": "ln_1",
      "canonicalSku": "AMUL-BUTTER-500G",
      "sourceId": "bigbasket",
      "qty": 1,
      "substitutable": true,
      "priceSnapshot": { "mrp": 295, "effectivePrice": 268, "etaMin": 14, "deliveryFee": 0 }
    },
    {
      "lineId": "ln_2",
      "canonicalSku": "MAGGI-MASALA-70G-PACK12",
      "sourceId": "blinkit",
      "qty": 1,
      "substitutable": true,
      "priceSnapshot": { "mrp": 168, "effectivePrice": 152, "etaMin": 9, "deliveryFee": 15 }
    },
    {
      "lineId": "ln_3",
      "canonicalSku": "BOAT-AIRDOPES-311PRO",
      "sourceId": "amazon",
      "qty": 1,
      "substitutable": false,
      "priceSnapshot": { "mrp": 4490, "effectivePrice": 1299, "etaMin": 1440, "deliveryFee": 0 }
    }
  ],
  "reoptimiseAtCheckout": true
}

From cart to one internal order

At checkout, QuickCart authorises a single payment hold for the basket total, creates one Order, and hands it to the Order Orchestrator. The orchestrator splits the order into sub-orders — one per source — and routes each sub-order by what that source can actually do.

Order & sub-order data model

One ORDER owns one PAYMENT and fans out to many SUB_ORDERs — exactly one per source. Each sub-order owns its items and, once fulfilled, a per-source SETTLEMENT. This shape lets QuickCart confirm, cancel, refund and settle a single source without touching the rest of the basket.

Orchestration as a saga

The hard part: five sources are independent systems with no shared database and no shared transaction. QuickCart cannot "BEGIN … COMMIT" across Blinkit and Amazon. So the orchestrator runs a saga — a sequence of local steps, each with a compensating action that undoes it if a later step fails.

1. Authorise, don't capture. Place a hold on the full basket total. Compensation: void the hold.
2. Re-verify per source. Right before placing, re-check stock & price for each sub-order (a fast line can vanish between "added to cart" and "checkout").
3. Place each sub-order — managed (commerce API) or assisted (picker task). Compensation: cancel the placed sub-order / cancel the picker task where still possible.
4. On failure, compensate the failed line only — re-source it to an in-stock alternative if it's substitutable, otherwise mark that line for refund. The rest of the basket proceeds.
5. Capture the confirmed subtotal. Money actually taken = value of confirmed lines + delivery fee; the held remainder is released.

// Saga: authorise → re-verify → place per source → compensate on failure → capture
const { mcp } = require('../mcp-adaptor/client');
const payment = require('../payment/psp');
const pickerQueue = require('../fulfillment/picker-queue');

// Sources that expose a partner commerce API (programmatic placement).
// Quick-commerce sources are assisted-only unless a partner agreement is enabled.
const PLACEABLE = new Set(['amazon', 'flipkart']);

async function orchestrate(order) {
  const saga = new Saga();
  try {
    // 1) hold funds for the whole basket (authorise, do NOT capture yet)
    const auth = await payment.authorise(order.paymentId, order.totalAuthorised);
    saga.add(() => payment.void(auth.id));                 // compensation

    // 2) one sub-order per source
    const subOrders = groupBySource(order.lines);

    // 3) place sub-orders in parallel, isolated from each other
    const settled = await Promise.allSettled(
      subOrders.map((so) => placeSubOrder(so, order, saga))
    );

    const confirmed = settled.filter(r => r.status === 'fulfilled').map(r => r.value);
    const failed    = subOrders.filter((_, i) => settled[i].status === 'rejected');

    // 4) re-source or refund each failed line — never fail the whole basket
    for (const so of failed) {
      const alt = await resourceLines(so.lines, order.pincode);   // find in-stock alternative
      if (alt) confirmed.push(await placeSubOrder(alt, order, saga));
      else     order.markLinesRefunded(so.lines);
    }

    // 5) capture ONLY what was actually confirmed
    const captureAmount = subtotal(confirmed) + deliveryFee(order);
    await payment.capture(auth.id, captureAmount);

    order.status = failed.length ? 'PARTIALLY_CONFIRMED' : 'CONFIRMED';
    await dispatchToLastMile(order, confirmed);            // pooled / direct / split — see §7
    return order;
  } catch (err) {
    await saga.compensate();          // void hold + cancel any placed sub-orders
    order.status = 'CANCELLED';
    throw err;
  }
}

async function placeSubOrder(so, order, saga) {
  // stock + price re-check immediately before placing (Doc 05)
  const stock = await mcp.call(so.sourceId, 'check_stock', { items: so.lines, location: order.pincode });
  if (!stock.allAvailable) throw new OutOfStock(so.sourceId, stock.missing);

  if (PLACEABLE.has(so.sourceId)) {
    const cart   = await mcp.call(so.sourceId, 'create_cart', { items: so.lines });
    const placed = await mcp.call(so.sourceId, 'checkout',    { cartId: cart.cartId, address: order.address });
    saga.add(() => mcp.call(so.sourceId, 'cancel_order', { ref: placed.ref }));
    return { sourceId: so.sourceId, mode: 'managed', ref: placed.ref, lines: so.lines, etaMin: placed.etaMin };
  }

  // handoff-only source → create an assisted picker task
  const task = await pickerQueue.enqueue({ sourceId: so.sourceId, lines: so.lines, pincode: order.pincode });
  saga.add(() => pickerQueue.cancel(task.id));
  return { sourceId: so.sourceId, mode: 'assisted', taskId: task.id, lines: so.lines, etaMin: task.etaMin };
}

class Saga {
  constructor() { this.undos = []; }
  add(fn) { this.undos.push(fn); }
  async compensate() { for (const undo of this.undos.reverse()) { try { await undo(); } catch (_) {} } }
}

module.exports = { orchestrate };

Fulfillment & delivery models

Once sub-orders are confirmed, the items still have to physically reach the shopper. QuickCart picks one of three delivery shapes per order, based on geography, source type and the ETA promise.

Order lifecycle state machine

The order moves through a single state machine; each sub-order runs its own parallel mini-lifecycle (PENDING → PLACED → PICKED → HANDED_OVER, or … → FAILED → RESOURCED). The order aggregates them: it is CONFIRMED only when every line is sourced, and PARTIALLY_CONFIRMED when some lines were dropped and refunded.

Money flow

One shopper-facing charge; many supplier payouts. The hold-then-capture pattern is what makes partial baskets safe: QuickCart never captures money for a line it couldn't actually source.

Edge cases we handle