Order Module — Storefront

{
  "data": <payload>,
  "message": "Success",
  "statusCode": 200,
  "metadata": { /* optional, e.g. pagination */ }
}

type OrderStatus     = "pending_payment" | "confirmed" | "cancelled";
type PaymentStatus   = "pending" | "paid" | "failed" | "refunded";
type Platform        = "APP" | "WEB" | "BOTH";
type OrderLineType   = "PRODUCT" | "GIFT";

type AddressBlock = {
  firstName: string;
  lastName: string;
  fullAddress: string;
  city: string;
  pincode: string;
  state: string;
  phone: string;
  country: string;
};

type OrderResponse = {
  id: string;
  orderNumber: string;
  customer: { id: string; name: string; email: string } | null; // The customer account that placed the order; null for legacy/guest orders.
  status: OrderStatus;
  paymentStatus: PaymentStatus;
  paymentProvider: string;          // e.g. "manual", "razorpay", "phonepe"
  paymentMethod: string;            // e.g. "cod", "upi", "card"
  platform: Platform;

  shippingAddress: AddressBlock;
  billingAddress: AddressBlock;
  customerNote: string | null;      // shopper's checkout instruction, snapshotted at placement

  subtotal: number;                 // subunits
  discountTotal: number;
  shippingTotal: number;
  taxTotal: number;
  grandTotal: number;

  vendorBreakdowns: OrderVendorResponse[];
  events: OrderEventResponse[];     // tail of audit-log rows (most recent first)

  /** Bootstrap data the storefront/SDK uses to complete a client-driven
   *  payment flow. Absent for synchronous providers like manual COD.
   *  `payload` is provider- and platform-specific — see below. */
  pendingClientAction: {
    provider: string;
    payload: Record<string, unknown>;
  } | null;

  placedAt: string;                 // ISO
  confirmedAt: string | null;
  paidAt: string | null;
  cancelledAt: string | null;
  cancellationReason: string | null;
};

type OrderVendorResponse = {
  id: string;
  vendorId: string;
  vendorNameAtOrder: string;        // snapshot
  fulfillmentStatus: "pending" | "fulfilled" | "delivered" | "cancelled";
  subtotal: number;
  discountAllocated: number;
  shippingCost: number;
  taxAmount: number;
  total: number;
  shippingProviderId: string | null;
  shippingMethod: string | null;
  trackingCode: string | null;
  awbNumber: string | null;
  taxBreakdown: TaxComponent[];     // aggregated by tax type across this vendor's lines + shipping
  shippingNetAmount: number | null;
  shippingTaxBreakdown: TaxComponent[];
  fulfilledAt: string | null;
  deliveredAt: string | null;
  cancelledAt: string | null;
  cancellationReason: string | null;
  lines: OrderLineResponse[];
};

type OrderLineResponse = {
  id: string;
  vendorId: string;
  variantId: string | null;
  productId: string | null;
  productSlug: string | null;       // CURRENT store slug, resolved live for `/product/{slug}` links; null if not store-visible
  sku: string;
  productNameAtOrder: string;       // snapshot
  variantNameAtOrder: string | null;
  imageAtOrder: string | null;
  hsnCodeAtOrder: string | null;    // GST classification snapshot from variant
  type: OrderLineType;
  quantity: number;
  unitPrice: number;
  lineSubtotal: number;             // tax-inclusive amount displayed
  discountAllocated: number;
  lineTotal: number;
  netAmount: number | null;         // pre-tax portion
  taxBreakdown: TaxComponent[];
};

type OrderEventResponse = {
  id: string;
  orderVendorId: string | null;
  eventType: string;
  actorType: "user" | "vendor" | "admin" | "system" | "webhook";
  actorId: string | null;
  actor: { id: string; name: string; email: string } | null; // Always null on the store surface (operator-only; staff PII not exposed to customers).
  source: string;
  changes: Record<string, unknown>;
  metadata: Record<string, unknown>;
  createdAt: string;
};

type ReturnResponse = {
  id: string;
  returnNumber: string;
  orderId: string;
  orderVendorId: string;
  customerId: string | null;
  vendorId: string;
  type: string;
  status: string;                   // e.g. requested / approved / picked_up / received / qc_passed / qc_failed / refunded / rejected / cancelled
  reasonCode: string | null;
  reasonNotes: string | null;
  refundAmount: number;             // subunits
  refundedAmount: number;
  externalRefundReference: string | null;
  shippingProvider: string | null;
  awbNumber: string | null;
  trackingCode: string | null;
  rejectionReason: string | null;
  qcFailureReason: string | null;
  requestedAt: string;
  approvedAt: string | null;
  rejectedAt: string | null;
  pickedUpAt: string | null;
  receivedAt: string | null;
  qcPassedAt: string | null;
  qcFailedAt: string | null;
  refundedAt: string | null;
  cancelledAt: string | null;
  lines: ReturnLineResponse[];
  photos: ReturnPhotoResponse[];
};

type ReturnLineResponse = {
  id: string;
  orderLineId: string;
  variantId: string | null;
  quantity: number;
  unitPrice: number;
  taxPortion: number;
  lineRefundAmount: number;
  reasonCode: string | null;
  reasonNotes: string | null;
  restocked: boolean;
};

{
  "data": {
    "providers": [
      { "id": "manual", "methods": ["cod", "bank-transfer"] },
      { "id": "phonepe", "methods": ["phonepe"] }
    ],
    "options": [
      {
        "key": "phonepe",
        "providerId": "phonepe",
        "method": "phonepe",
        "label": "PhonePe",
        "description": "UPI, cards, net banking and wallets via PhonePe.",
        "logoUrl": "https://cdn.example.com/settings/phonepe.png",
        "badge": "Fastest",
        "isDefault": true
      },
      {
        "key": "manual.cod",
        "providerId": "manual",
        "method": "cod",
        "label": "Cash on Delivery",
        "description": "Pay with cash when your order arrives.",
        "logoUrl": null,
        "badge": null,
        "isDefault": false
      }
    ]
  },
  "message": "Success",
  "statusCode": 200
}

// provider "razorpay" — Checkout SDK
{ "razorpayOrderId": "order_…", "keyId": "rzp_…", "amount": 125000, "currency": "INR", "prefill": { } }

// provider "phonepe", x-platform: WEB — hosted redirect
{ "phonepeOrderId": "OMO…", "redirectUrl": "https://…", "expireAt": 1703756259307, "amount": 125000 }

// provider "phonepe", x-platform: APP — mobile SDK
{ "phonepeOrderId": "OMO…", "token": "…", "merchantId": "…",
  "environment": "SANDBOX", "flowId": "…", "expireAt": 1703756259307, "amount": 125000 }

{
  "paymentProvider": "razorpay",   // trimmed, min 1
  "paymentMethod": "upi",          // trimmed, min 1
  "billingAddress": {              // optional — when omitted, billing copies shipping
    "firstName": "Ada",
    "lastName": "Lovelace",
    "fullAddress": "221B Baker Street",
    "city": "London",
    "pincode": "110001",
    "state": "Delhi",
    "phone": "+919876543210",
    "country": "IN"
  },
  "customerNote": "Leave with the security desk" // optional, trimmed, max 500 chars
}

{ "reason": "Changed my mind" }  // optional, 1..500 chars

{
  "data": {
    "vendors": [
      {
        "orderVendorId": "01J9...",
        "vendorId": "01J9...",
        "returnable": true,
        "reason": null,
        "windowExpiresAt": "2026-05-20T00:00:00.000Z",
        "eligibleReasons": ["DAMAGED", "WRONG_ITEM", "NOT_AS_DESCRIBED"],
        "policyText": "Returns within 7 days of delivery..."
      }
    ]
  }
}

{
  "contentType": "image/jpeg",
  "fileSizeBytes": 524288         // max 20 MiB (20 * 1024 * 1024)
}

{
  "data": {
    "storageKey": "returns/2026-05/abc.jpg",
    "uploadUrl": "https://s3.../signed-put-url",
    "expiresAt": "2026-05-13T11:45:00.000Z"
  }
}

{
  "orderVendorId": "01J9...",                // sub-order being returned
  "reasonCode": "DAMAGED",                   // 1..64 chars
  "reasonNotes": "Box arrived crushed",      // optional, max 2000 chars
  "lines": [
    {
      "orderLineId": "01J9...",
      "quantity": 1,                          // integer >= 1
      "reasonCode": "DAMAGED",                // optional per-line override
      "reasonNotes": "Top half dented"        // optional, max 2000 chars
    }
  ],
  "photoKeys": ["returns/2026-05/abc.jpg"]   // optional, max 20 keys, from POST /store/returns/photos
}