Checkout - API Reference

Audience: Frontend engineers, mobile engineers, backend engineers, QA, and API consumers. Scope: The three customer checkout routes and the four admin session routes. Payment has no HTTP surface.

1. Documentation Evidence

2. Module Summary

3. Concepts and Terminology

4. API Surface Map

{id} is always a uuid7 public_id; no integer PK is exposed.

5. Auth, Identity, and Permissions

Another customer's session and a session that does not exist both return 404 with the same code — a 403 would confirm the id is real. Do not distinguish them.

6. DTO and Model Reference

6.1 StartCheckoutDto

Do not send prices, discounts, shipping or totals. The server recalculates all of them, and the request is rejected outright if any unknown property is present — not silently stripped.

6.2 Params DTO

CheckoutSessionParamsDto { id } — uuid7.

6.3 Admin query DTO

status, customerId, createdFrom, createdTo, minTotal, maxTotal, offset pagination (page/size), sort by createdAt / updatedAt / expiresAt / grandTotal.

6.4 Response DTOs

Start/active/detail share the session shape:

{
  "checkout": { "id": "0198f2c1-…", "status": "pending_payment",
                "expiresAt": "…", "expiresInSeconds": 900, "version": 1 },
  "pricing": { "currency": "NPR", "subtotal": 250000, "discountAmount": 20000,
               "shippingAmount": 15000, "shippingDiscountAmount": 0, "grandTotal": 245000,
               "anyPriceChanged": true },
  "items": [{ "id": "…", "productId": "…", "name": "…", "sku": "ABC-1",
              "unitPrice": 100000, "mrp": 120000, "quantity": 2, "lineTotal": 200000,
              "priceChange": { "changed": true, "previousPrice": 95000, "currentPrice": 100000 },
              "reserved": true }],
  "promotions": [{ "id": "…", "promotionId": "…", "name": "Festival 20%",
                   "couponCode": "SAVE20", "discountAmount": 20000, "shippingDiscountAmount": 0 }],
  "shipping": { "districtName": "Kathmandu", "municipalityName": "…", "ward": 5,
                "street": "…", "landmark": null, "postalCode": null,
                "recipientName": "…", "recipientPhone": "+977…", "fee": 15000 },
  "payment": { "ready": true, "amountDue": 245000, "currency": "NPR" }
}

All money is integer minor units (245000 = NPR 2,450.00) — never parse as float. grandTotal is database-enforced; display any part without recomputing.

7. Enum Reference

8. Endpoint Reference

8.1 POST /api/mobile/checkout

Purpose

Turn the cart into a validated, price-frozen purchase attempt that holds stock. 201 on create; 200 when an existing live session was returned.

Auth and Permissions

JwtAuthGuard; CUSTOMER_CHECKOUT_ATTEMPT 10/min (account-keyed).

Request

{ "addressId": "0198f2c1-…", "couponCode": "SAVE20", "cartVersion": 7 }

Prices, discounts, shipping and totals must not be sent — the server recalculates; any unknown property rejects the request.

Response

201 (create) or 200 (existing live session — the response is identical either way, so a repeat POST, retry after timeout, or two tabs are all safe). Session shape per §6.4.

Side Effects

One transaction: inventory + promotion reservations, price/shipping/promotion freeze, session + snapshot rows. A failed checkout leaves nothing behind.

Error Cases

CHECKOUT_CART_NOT_READY, CHECKOUT_PRODUCT_UNAVAILABLE and CHECKOUT_INSUFFICIENT_STOCK are one builder (checkoutNotReady) choosing between three codes by precedence — every one of them carries all three detail fields (blockingReasons, unavailableVariantIds, shortfalls), not only the one its name suggests. A client can read whichever fields are non-empty regardless of which code came back.

The five things that shape the UI

1. A repeat POST returns the SAME session with a 200, not an error — no button guard needed.
2. expiresInSeconds is server-computed — run the countdown from it, never from the device clock. At zero, re-fetch: the session reports status: "expired".
3. priceChange.changed is a warning, not a blocker — show "the price of X changed from A to B"; the customer has not paid yet.
4. reserved: false on a line is normal — the product is not stock-tracked; nothing to hold.
5. status is already correct for expiry — never compare expiresAt yourself; a session past expiry reads expired regardless of any background job.

8.2 GET /api/mobile/checkout/active

Purpose

Fetch my live session (for countdown polling or resume). CUSTOMER_READ 60/min.

Response

200 — session shape. An expired session reads expired; the customer starts again.

8.3 POST /api/mobile/checkout/:id/cancel

Purpose

Cancel my own pending session. Releases the held stock and the coupon slot, unlocks the cart. CUSTOMER_WRITE 20/min.

Error Cases

8.4 GET /api/checkout/sessions

Purpose

Admin session list. Checkout_READ; ADMIN_READ 30/min. Filters: status, customerId, createdFrom, createdTo, minTotal, maxTotal; offset pagination; sort by createdAt/updatedAt/expiresAt/grandTotal.

8.5 GET /api/checkout/sessions/:id

Detail. 404 CHECKOUT_SESSION_NOT_FOUND.

8.6 POST /api/checkout/sessions/:id/cancel

Purpose

Cancel a pending_payment session an operator judges fraudulent or duplicated. Releases holds + coupon slot, unlocks the cart, records which administrator acted. Checkout_UPDATE; ADMIN_WRITE 10/min.

8.7 POST /api/checkout/sessions/:id/expire

Purpose

Force-expire a session stuck at a payment gateway that never called back — the only lever for that state, because the automatic sweep deliberately never touches payment_in_progress. Same release semantics as cancel, with the administrator recorded.

9. Flow Diagrams

9.1 Route Ownership

9.2 Request Sequence (start)

9.3 Error Branch (start)

10. Pagination, Sorting, Filtering, and Search

Customer endpoints are single-session (never paginated).

11. Caching, Jobs, and External Integrations

13. Mandatory Deep API Documentation Pack

13.1 Route-by-Route Completeness Matrix

13.2 Request/Response Exhaustiveness

Covered in §8: minimal start request (§6.1/8.1), full session response (§6.4), the 200-on-repeat behavior (§8.1 point 1), the expiry-read-predicate behavior (§8.1 point 5), domain errors per endpoint (§8 error tables), the same-404-for-others/unknown rule (§5), rate-limit behavior (10/min checkout budget).

13.3 API Diagram Pack

Route ownership (§9.1), request sequence (§9.2, backend §7.1), error decision tree (§9.3), payment-transition flow (backend §7.2 — no HTTP surface).

13.4 Consumer Integration Notes

13.5 API Tradeoffs and Rationale

13.6 API Change Impact

14. Zero-Omission API Checklist

• Every controller route is documented (§4, §8, §13.1).
• Every parent route prefix and runtime URL is documented (§2, §4).
• Every DTO field, enum, default, transform and validator is documented (§6, §7).
• Every response field and nullable field is documented (§6.4, §8).
• Every auth, guard, permission and guest identity branch is documented (§5).
• Every success, validation, not-found, conflict, rate-limit and server-error branch is documented (§8).
• Every DB read/write, queue job and external call is documented (§11, backend §9).
• Every route has examples for minimal request, success response and representative failures (§8).
• Every endpoint family has route, sequence and error diagrams (§9, backend §7).
• Every tradeoff and compatibility risk is documented (§13.5, §13.6).
• The API doc links to backend and features/flows (§1, See Also).

15. Integration Checklist

• Every route from controllers is documented.
• Every DTO field is documented.
• Every enum value is documented.
• Every response envelope is documented.
• Every error code is documented.
• Every auth guard and permission is documented.
• Every cache key, queue job and external call is documented.
• Every diagram matches the current code.
• The API doc links to backend and features/flows.

See Also

• Backend doc: /docs/developer/checkout/backend
• Features and flows doc: /docs/developer/checkout/feature
• TDD: not yet published