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;
  status: OrderStatus;
  paymentStatus: PaymentStatus;
  paymentProvider: string;          // e.g. "manual", "razorpay"
  paymentMethod: string;            // e.g. "cod", "upi", "card"
  platform: Platform;

  shippingAddress: AddressBlock;
  billingAddress: AddressBlock;

  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 an SDK-driven
   *  payment flow (Razorpay, Stripe, etc.). Absent for synchronous
   *  providers like manual COD. */
  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;
  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;
  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;
};

{
  "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"
  }
}

{ "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
}