Order Module - Feature List

1. Feature Overview

Order uses a mixed execution model:

• synchronous initiation for checkout and buy-now payment start
• asynchronous processing for cancellation, refund processing, payment reconciliation/retries, and auto-cancel

The customer/mobile surface is authenticated and mounted through the shared mobile composition layer.

2. Route Ownership and Surfaces

Swagger tags used by order controllers:

• Orders (Mobile)
• Orders (Admin)

3. Admin Feature Matrix

4. Customer/Mobile Feature Matrix

Notes:

• idempotency-key header is required for checkout and buy-now.
• Equivalent mobile endpoints are available at /api/mobile/orders/... via routing composition.

5. Key Business Rules

• Physical products (thangka, singing_bowl, statue, jewellery) create orders with orderType: "physical"
• Checkout requires an active cart with at least one valid sellable product.
• Cancellation and refund state transitions are gated by current order status.
• Monetary values are stored in paisa and guarded by DB non-negative constraints.

6. Physical Product Support

6.1 Supported Product Types

6.2 Error Codes

7. State Models

7.1 Order status lifecycle

created -> payment_pending -> paid / payment_failed -> cancelled / refund_requested -> refund_approved / refund_rejected

7.2 Actor provenance in status history

order_status_history writes use explicit actor model:

• customer: customer-initiated state changes
• admin: admin-user initiated changes (includes subadmins)
• system: background jobs, webhook side effects, auto-cancel/reconciliation markers

7.3 Payment initiation model

Checkout and buy-now return one of:

• initiationType = form_post
• initiationType = redirect

8. Caching Strategy

Read-side keyspaces:

• order:customer:list:
• order:detail:
• order:admin:list:
• order:admin:detail:

Configured TTLs:

• ORDER_HISTORY_CACHE_TTL_SECONDS (default 120)
• ORDER_ADMIN_CACHE_TTL_SECONDS (default 60)

Invalidation triggers:

• customer/admin async mutations invalidate order list/detail keyspaces

9. Rate Limiting

Customer operation limits:

• ORDER_CHECKOUT_RATE_LIMIT (default 10)
• ORDER_CANCEL_RATE_LIMIT (default 10)
• ORDER_REFUND_REQUEST_RATE_LIMIT (default 5)
• ORDER_CHECKOUT_RATE_WINDOW_SECONDS (default 60)

Admin operation limits:

• ORDER_ADMIN_OPERATION_RATE_LIMIT (default 120)
• ORDER_ADMIN_RATE_WINDOW_SECONDS (default 60)

Safety behavior:

• Redis sliding-window checks are used for customer and admin operations.
• Limit breaches throw RateLimitExceededException and return RATE_LIMIT_EXCEEDED.
• Retry/backoff windows and DLQ warning thresholds are environment-controlled in processing runtime.

10. Queue/Worker Features

Maintenance behavior:

• outbox dispatch with queue ownership filtering (orders, orders_maintenance, cart)
• retention cleanup for completed/failed outbox rows
• failed-job threshold monitoring with alert logs

Flow diagram:

11. Error UX Mapping

12. Release/QA Checklist

• Checkout path returns payment-init payload with valid initiationType and gatewayPayload.
• Buy-now path enforces product eligibility and promo-code validation behavior.
• Customer cancel returns 202 and request is pollable via /orders/requests/:requestId.
• Admin cancel/process-refund paths enforce Orders_UPDATE permission.
• Status history rows capture actor provenance (customer/admin/system) correctly.
• Processor jobs (order.payment_*, cancel, refund, auto-cancel) update order state and invalidate caches.
• Outbox dispatch/cleanup cron pipeline runs on orders_maintenance queue.
• Mobile-composed routes (/api/mobile/orders/...) resolve through MobileModule routing.
• Payment redirect callbacks and /api/payments/result handoff are functional.

13. Integration Flows

13.1 Checkout Flow

A customer completes checkout from an active cart with payment initiation.

1. Customer calls POST /api/orders/checkout with idempotency-key header.
2. System validates active cart exists and contains valid sellable products.
3. System calculates order totals from cart items and applies any applied coupon discount.
4. System creates order with status payment_pending.
5. System creates order_status_history entry with actor customer.
6. System calls payment gateway to initiate payment, returning initiationType (form_post or redirect) with gatewayPayload.
7. Order is now await payment completion via gateway callback or redirect handling.

13.2 Admin Refund Flow

An admin processes a customer refund request after order payment was successful.

1. Customer calls POST /api/orders/:id/request-refund to submit refund request.
2. System updates order status to refund_requested.
3. Admin calls GET /api/admin/orders/:id to review order and refund request.
4. Admin calls POST /api/admin/orders/:id/process-refund with { action: "approve" | "reject", remarks: string }.
5. If approve: system immediately sets order to refund_approved (manual refund completed).
6. If reject: system sets order to refund_rejected, customer can view rejection via order detail.
7. No payment gateway refund API call is made in this phase.

Related payment docs:

• apps/fumadocs/content/docs/developer/payment/cart-checkout-flow.mdx

Time fields in this module are stored as timezone-aware values and should be handled as ISO-8601 instants by API consumers.

---

See Also

• API Reference: See Order - API & Integration Guide Section 7 (Endpoint Reference + Payload Cheatsheet) for complete request/response DTOs.
• Backend Reference: See Order - Backend Documentation Section 3 (Data Model) for schema details.