Checkout - API Reference

Audience: Frontend engineers, mobile engineers, backend engineers, QA, and API consumers. Scope: The five 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.1a QuoteCheckoutDto

No cartVersion — a quote writes nothing, so there is no lost update to guard, and requiring it would fail the first quote a client makes, before it has read the cart at all.

6.1b PayCheckoutDto

The same four fields StartCheckoutDto carries, plus:

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.

6.4a Quote response — CheckoutQuoteResponseDto

{
  "pricing": { "currency": "NPR", "subtotal": 89000, "discountAmount": 5000,
               "shippingAmount": 15000, "shippingDiscountAmount": 0, "grandTotal": 99000 },
  "shipping": { "fulfilmentType": "delivery", "serviceable": true, "fee": 15000,
                "districtName": "Kathmandu" },
  "coupon": { "code": "SAVE20", "applied": true, "discountAmount": 5000,
              "shippingDiscountAmount": 0, "message": "…" },
  "readiness": { "ready": true, "blockingReasons": [], "liveSessionId": null,
                 "liveSessionStatus": null }
}

coupon is null when the request carried no coupon code. shipping.fee is null exactly when shipping.serviceable is false; shipping.districtName is always null for a pickup. readiness.ready is exactly readiness.blockingReasons.length === 0. readiness.liveSessionId / liveSessionStatus are non-null when the customer already has a live session, so a client can offer a release rather than showing a blocked cart with no action.

7. Enum Reference

8. Endpoint Reference

8.0a POST /api/mobile/checkout/quote

Purpose

Price the basket for a chosen address and coupon without writing anything — no session, no stock hold, no promotion hold, no cart lock, no transaction. Everything the create path THROWS for as a business refusal (unserviceable district, inapplicable coupon, locked cart, unavailable items) comes back here as readiness and coupon data instead, so a client can show a disabled state with a sentence rather than an error. POST for the body, not for the effect — a coupon code does not belong in a query string, and the response must never be cached, since it is a price.

Auth and Permissions

JwtAuthGuard; CUSTOMER_CHECKOUT_QUOTE 40/min (account-keyed) — four times the pay budget, because this writes nothing, holds nothing and takes no lock.

Request

{ "fulfilmentType": "delivery", "addressId": "0198f2c1-…", "couponCode": "SAVE20" }

All fields optional; fulfilmentType defaults to delivery.

Response

200. Shape per §6.4a.

Side Effects

None.

Error Cases

What it still refuses is malformed or unauthorised input, not a business condition — those come back as readiness/coupon data with a 200.

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.1a POST /api/mobile/checkout/pay

Purpose

Freeze the basket and start the payment, in one request. Revalidates the cart, holds the stock, freezes the amount payable and starts the payment. This is what closes the gap the old two-step flow left open: POST /checkout used to be fired from the review step, minutes before payment, so the cart sat locked and stock held while the customer was still deciding how to pay. Both routes still exist and still work — this route exists so the freeze and the payment start happen together.

Auth and Permissions

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

Request

The StartCheckoutDto fields plus method and expectedGrandTotal — DTO per §6.1b.

{ "addressId": "0198f2c1-…", "couponCode": "SAVE20", "method": "esewa", "expectedGrandTotal": 99000 }

Response

200 — PaymentResponseDto, the same shape POST /api/payments returns.

Side Effects

The create transaction's usual holds (inventory, promotion, session, snapshot rows), plus starting the payment attempt. No compensating write on a payment-start failure: create refuses inside its own transaction and rolls back cleanly when the total or the destination does not match, leaving no session, no hold and an untouched cart. A failure inside the payment start is repaired by PaymentAttemptService itself, which returns the session to pending_payment with its holds intact so the customer can press Pay again — see backend §6.x PaymentAttemptService.

Error Cases

CHECKOUT_SESSION_MISMATCH exists specifically for two tabs pressing Pay with different addresses: equal totals do not make it safe to resume the other tab's session, because two addresses in the same district can cost the same and are not the same place.

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