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 (productKind = "physical") create orders with orderType: "physical"
• Checkout requires an active cart with at least one valid sellable product.
• Checkout and buy-now both require shipping district selection on the active cart.
• Mobile order detail (GET /api/mobile/orders/:id) includes order-level receiver snapshot fields (receiver, contactNumber) and fulfillmentStatus for shipping timeline rendering.
• Cancellation and refund state transitions are gated by current order status.
• Monetary values are stored in integer minor units (for Stripe, USD cents) and guarded by DB non-negative constraints.

6. Physical Product Support

6.1 Supported Product Types

Buy-now restriction: care_package items are blocked from buy-now. Use cart checkout for care package purchases. Error code: ORDER_BUYNOW_CARE_PACKAGE_NOT_ALLOWED.

6.2 Error Codes

| Error Code | HTTP | Trigger | |---|---|---|---| | ORDER_BUYNOW_CARE_PACKAGE_NOT_ALLOWED | 422 | Buy-now attempted with care_package productKind | | ORDER_COD_PHYSICAL_ONLY | 400 | COD checkout attempted on digital-only or care-package-only cart or buy-now product | | ORDER_NOT_COD_METHOD | 400 | Admin cash collection attempted on non-COD order | | CART_CARE_PACKAGE_ITEM_NOT_PHYSICAL | 422 | Cart item is not a physical product when attaching care package | | ORDER_FULFILLMENT_NOT_PHYSICAL_TYPE | 400 | Fulfillment advance on non-physical/mixed order | | ORDER_FULFILLMENT_NOT_DIGITAL_TYPE | 400 | Digital delivery on non-digital/mixed order | | ORDER_ACTIVATE_CARE_PACKAGE_NOT_APPLICABLE | 400 | Activate care package on non-care_package order | | ORDER_NOT_PAID | 400 | Action requires paid order status | | ORDER_SERIAL_ITEM_NOT_PHYSICAL | 422 | Serial number assigned to non-physical item | | ORDER_SERIAL_ALREADY_ASSIGNED | 409 | Item already has a serial number assigned | | ORDER_SERIAL_AFTER_DELIVERED | 422 | Serial assignment after order is delivered | | ORDER_SERIAL_DUPLICATE | 409 | Serial number already in use for another item |

6.3 Care Package Product Support

Business rules for care package orders:

• Care-package-only carts produce orderType = "care_package".
• No shippingDistrict required; shippingFee = 0 for care-package-only orders.
• Mixed carts (physical + care_package) produce orderType = "mixed"; shipping required for physical items.
• Checkout creates care_package_subscriptions rows with status = "pending_activation".
• Activation is triggered via BullMQ after payment success.

7. State Models

7.1 Order status lifecycle

Online orders: created -> payment_pending -> paid / payment_failed -> cancelled / refund_requested -> refund_approved / refund_rejected

COD orders: created -> payment_pending with paymentStatus = "cod_pending" after reservation. Admin cash collection changes paymentStatus to "cod_collected" without changing orderStatus to "paid".

Warranty coupling:

• Warranty claims and warranty-status reads are allowed only while the linked order remains warranty-eligible.
• refund_requested and refund_pending do not block warranty yet.
• refund_approved, cancelled, and payment_failed block warranty operations.
• COD orders remain warranty-ineligible until admin collection changes paymentStatus from cod_pending to cod_collected.

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
• initiationType = cod — COD only; no gateway redirect. Order remains payment_pending with paymentStatus = "cod_pending" until admin collection. Frontend navigates to returnUrl directly.

That COD pending window is fulfillment-eligible but not warranty-eligible.

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.
• Care package items are rejected from buy-now with ORDER_BUYNOW_CARE_PACKAGE_NOT_ALLOWED.
• Admin POST /:id/activate-care-package validates order type and subscription pending status.
• Admin PATCH /:id/items/:orderItemId/serial assigns serial number and rejects duplicates with ORDER_SERIAL_DUPLICATE.

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. Cart remains visible in customer flow while payment is pending/failed.
8. Cart is cleared only after payment success processing (order.payment_success -> cart clear job).
9. Order is now awaiting 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.

Warranty effect:

• Approval makes the order permanently warranty-ineligible.
• Rejection keeps the order warranty-eligible, subject to the normal payment and expiry checks.

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.