POS - API Reference

Audience: Frontend engineers (admin panel), backend engineers, QA, and API consumers. Scope: The 13 admin-only counter routes under /api/admin/pos/ — sale drafting, completion, cancellation, and customer/product lookup.

1. Documentation Evidence

2. Module Summary

3. Concepts and Terminology

4. API Surface Map

5. Auth, Identity, and Permissions

• ParseUUIDPipe on every :publicId and :productPublicId — a malformed id is a clean 400.
• Rate limits key on the user, not the IP — every till in a shop shares one public address.

6. DTO and Model Reference

6.1 OpenPosSaleDto — POST /sales

Deliberately no fulfilment field. Every sale opens as a pickup; delivery is chosen with PATCH /fulfilment, the only endpoint that can take an address in the same request. Sending fulfilment here is rejected by forbidNonWhitelisted.

6.2 AttachPosCustomerDto — PATCH /sales/{publicId}/customer

6.3 CreatePosWalkInDto — POST /sales/{publicId}/customer

6.4 UpsertPosLineDto — PUT /sales/{publicId}/items/{productPublicId}

6.5 SetPosFulfilmentDto — PATCH /sales/{publicId}/fulfilment

PosDeliveryAddressDto: districtId (int ≥1), municipalityName (≤120), ward (int 1–40), recipientName (≤120), recipientPhone (E.164 ^\+[1-9][0-9]{7,14}$), street (≤200), landmark (optional ≤200), postalCode (optional, five digits).

6.6 CompletePosSaleDto — POST /sales/{publicId}/complete

6.7 CancelPosSaleDto — POST /sales/{publicId}/cancel

6.8 ListPosSalesQueryDto — GET /sales

6.9 PosLookupQueryDto — both lookup routes

6.10 Response DTOs

7. Enum Reference

8. Endpoint Reference

8.1 GET /api/admin/pos/lookup/customers?search=

Purpose

Find a returning customer at the till by name, email or phone. Bounded and paginated: two characters minimum, and it returns identity fields only — never addresses or purchase history, which belong on the customer's own detail endpoint.

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard
• Permission: Pos_READ
• Rate limit: PUBLIC_SEARCH

Request

Response

200 — { items: [{ customerId, name, email?, phone? }] }. Only status = 'active', not soft-deleted, customers match.

Side Effects

None — a read over customers.

Error Cases

8.2 GET /api/admin/pos/lookup/products?search=

Purpose

Find a sellable product by name or SKU. Only published, non-deleted products with selling_price <= mrp match — a counter must not become the way unpublished stock leaves the building.

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permission: Pos_READ · Rate limit: PUBLIC_SEARCH

Request

Response

200 — { items: [{ productPublicId, name, sku?, mrp, sellingPrice }] }. All money in minor units.

Side Effects

None.

Error Cases

8.3 POST /api/admin/pos/sales

Purpose

Open a new draft. customerId is required — a sale cannot exist without a customer, so an unknown walk-in is created via POST /sales/{id}/customer first. Always opens as a pickup; delivery is chosen later with PATCH /fulfilment.

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permission: Pos_CREATE · Rate limit: ADMIN_POS_WRITE

Request

{ "paymentMethod": "pos_cash", "customerId": "018f1e2a-0000-7000-8000-000000000001" }

Response

201 — the PosSaleDto with empty items, status: "draft", fulfilment: "pickup".

Side Effects

pos_sale row + created audit event, same transaction.

Error Cases

Edge Cases

• paymentMethod is changeable until completion — the field is on the sale, not fixed at open.
• Sending fulfilment is rejected outright (forbidNonWhitelisted).

8.4 GET /api/admin/pos/sales

Purpose

The reconciliation list (§51). Filters: status, fulfilment, payment method, customer, administrator, and a from/to date range on created_at.

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permission: Pos_READ · Rate limit: ADMIN_READ

Request

Response

200 — { items: [PosSaleListItemDto], metadata: { count, page, size } }, newest first.

Side Effects

None. Page and total come from one transaction so they cannot disagree.

8.5 GET /api/admin/pos/sales/{publicId}

Purpose

One sale with its lines, for the detail view and the receipt.

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permission: Pos_READ · Rate limit: ADMIN_READ

Response

200 — the full PosSaleDto. orderNumber/orderPublicId are NULL until completion.

Error Cases

8.6 GET /api/admin/pos/sales/{publicId}/timeline

Purpose

The §42 audit trail, oldest first — who did what to this sale, in the order it happened.

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permission: Pos_READ · Rate limit: ADMIN_READ

Response

200 — { events: [{ publicId, eventType, fromStatus?, toStatus?, actorName?, reason?, createdAt }] }. actorName is NULL for sweep cancellations and for offboarded administrators.

Error Cases

8.7 PATCH /api/admin/pos/sales/{publicId}/customer

Purpose

Point the draft at a customer who already has an account (e.g. after correcting a mistaken walk-in creation).

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permission: Pos_UPDATE · Rate limit: ADMIN_POS_WRITE

Request

{ "customerId": "018f1e2a-0000-7000-8000-000000000001" }

Response

200 — the refreshed PosSaleDto.

Side Effects

Changing the customer resets the sale to a pickup: the saved address belonged to one person, so fulfilment, deliveryAddressId and shippingAmount are cleared together (CLEAR_DELIVERY_ON_CUSTOMER_CHANGE). The operator must re-choose delivery for the new customer — re-render the fulfilment step from the response, never assume it survived. customerCreated is reset to false.

This applies to POST /customer (create a walk-in) exactly as it does to PATCH /customer. Until 2026-08-17 it did not: creating a walk-in customer cleared only the address, leaving fulfilment = 'delivery' beside a NULL delivery_address_id, which chk_pos_sale_fulfilment_address refuses. The ordinary sequence — choose delivery, type the address, then discover the customer has no account — produced a 23514 at the till, and because the account, its account row and the outbox invite all rolled back with it, retrying hit the same error indefinitely. The reset had been applied to one of the two call sites.

Error Cases

8.8 POST /api/admin/pos/sales/{publicId}/customer

Purpose

Create a walk-in account and attach it to the sale — account, invitation and sale update are ONE transaction.

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permission: Pos_CREATE · Rate limit: ADMIN_POS_WRITE

Request

{ "name": "Sita Sharma", "email": "sita.sharma@example.com", "phone": "+9779812345678" }

Response

200 — { sale, customerId, invitationQueued: true }.

Side Effects

• customers + account rows (email verified FALSE — the operator typed it, nobody proved it; setting a password through the link is what proves it).
• Outbox row pos.walk_in_created (invite queued at creation, not completion — the account exists either way).
• Audit event customer_created (with the email; never the token).

The account is created with NO password. The customer receives an emailed set-password link that never expires but is single-use. There is nothing for a client to display, copy or resend. Never suggest a password is emailed.

Error Cases

8.9 PUT /api/admin/pos/sales/{publicId}/items/{productPublicId}

Purpose

Set the quantity of one product on the draft. The body is the FINAL quantity, not a delta — scanning the same barcode twice sends quantity: 2, not two calls of 1. Idempotent: sending the same quantity twice changes nothing.

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permission: Pos_UPDATE · Rate limit: ADMIN_POS_WRITE

Request

{ "quantity": 2 }

Response

200 — the refreshed PosSaleDto with recomputed totals. The line freezes the product's current sellingPrice (and mrp) — a counter line is a price snapshot, unlike a cart line.

Side Effects

pos_sale_item upsert (ON CONFLICT (pos_sale_id, product_id) DO UPDATE), totals recomputed from the persisted lines, audit event item_added/item_quantity_changed.

Error Cases

8.10 DELETE /api/admin/pos/sales/{publicId}/items/{productPublicId}

Purpose

Take an item back off the counter before payment. The line is hard-deleted — the record of what the customer actually bought is checkout_session_item and then order_item.

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permission: Pos_UPDATE · Rate limit: ADMIN_POS_WRITE

Response

200 — the refreshed PosSaleDto with recomputed totals.

Error Cases

8.11 PATCH /api/admin/pos/sales/{publicId}/fulfilment

Purpose

Choose how the goods leave the shop. The only endpoint that can take an address in the same request — either a saved one (addressPublicId) or a new one (address), which is saved to the customer's own address book.

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permission: Pos_UPDATE · Rate limit: ADMIN_POS_WRITE

Request

Pickup:

{ "fulfilment": "pickup" }

Delivery with a new address:

{
  "fulfilment": "delivery",
  "shippingAmount": 15000,
  "address": {
    "districtId": 27, "municipalityName": "Lalitpur Metropolitan City", "ward": 5,
    "recipientName": "Sita Sharma", "recipientPhone": "+9779812345678",
    "street": "Jhamsikhel, Ward 5", "landmark": "Opposite the community school",
    "postalCode": "44700"
  }
}

Delivery with a saved address:

{ "fulfilment": "delivery", "addressPublicId": "018f1e2a-0000-7000-8000-000000000009" }

Response

200 — the refreshed PosSaleDto.

Side Effects

• Pickup: clears the address and forces shippingAmount to 0.
• Delivery: resolves the saved address (scoped to THIS customer in the query) or inserts a new customer_addresses row with is_default: false — the POS transaction deliberately does not take the default-address advisory lock.
• grandTotal is recomputed in the same statement that writes shippingAmount, from the row's own subtotal and discountAmount.

Error Cases

8.12 POST /api/admin/pos/sales/{publicId}/complete

Purpose

Take the money and produce the order — ONE transaction: stock moves, the payment is recorded, the order is created, and for a pickup the goods are handed over. There is no state in which a customer has paid and no order exists. Returns the order number for the receipt.

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permission: Pos_CREATE · Rate limit: ADMIN_POS_COMPLETE (30/min — each call takes money)

Request

{ "paymentReference": "TXN-88213" }

paymentReference is optional and permitted only for pos_card and pos_qr. Sending one with pos_cash is rejected. It is recorded, never validated — the platform does not check it against any provider, and a client must not present it as verified.

Response

200 — { sale (status picked_uporordered), orderNumber, orderPublicId }.

Side Effects

Cart (born converted), checkout session (born completed, channel: "pos"), frozen checkout_session_items, settled payment_attempt (born succeeded, gateway_transaction_id = POS-{saleNumber}), reservation finalize, order (createFromCheckout with executor: tx), pickup hand-over to delivered, outbox pos.sale_completed, events payment_recorded + completed, and post-commit invalidation of the inventory cache domain.

Error Cases

POS_PRODUCT_PRICE_CHANGED and POS_INSUFFICIENT_STOCK mean nothing was charged and nothing was reserved — the whole completion rolled back, so the sale is still a live draft.

Edge Cases

• Replayed completion: the four partial unique indexes (uq_pos_sale_{cart,checkout_session,payment_attempt,order}_id) plus the guarded WHERE status = 'draft' finalise make a retry a 409, never a second charge.
• A delivery sale's order stays at confirmed for the normal lifecycle; a pickup's order is driven straight to delivered (return window starts, purchase reviewable).

8.13 POST /api/admin/pos/sales/{publicId}/cancel

Purpose

Abandon a draft before any money has moved. Only reachable from draft — once completed, the correction is an order cancellation and refund, owned by the Order module.

Auth and Permissions

• Auth: JwtAuthGuard + RoleGuard · Permission: Pos_DELETE · Rate limit: ADMIN_POS_WRITE

Request

{ "reason": "Customer changed their mind" }

Response

200 — the PosSaleDto with status: "cancelled".

Error Cases

9. Flow Diagrams

9.1 Route Ownership

9.2 Request Sequence (complete)

9.3 Error Branch (completion)

10. Pagination, Sorting, Filtering, and Search

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 and full payloads for every body endpoint (§6, §8.3/8.8/8.11/8.12), the final-quantity semantics of PUT (§8.9), the mutually-exclusive address fields (§8.11), the pickup-reset on customer change (§8.7), the never-expiring single-use invite (§8.8), the full PosSaleDto shape (§6.10), every nullable field, and per-endpoint error tables with the exact codes and the "nothing was charged" meaning of the two completion conflicts (§8.12).

13.3 API Diagram Pack

Route ownership (§9.1), completion sequence (§9.2), completion error tree (§9.3), plus the activity/till flow and queue topology in the feature and backend docs.

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, nested field, enum, default, transform, and validator is documented (§6, §7).
• Every response field, nullable field, generated field, and omitted raw entity field is documented (§6.10, §8).
• Every auth, guard, permission, role, public decorator, and guest identity branch is documented (§5) — there is no public/guest surface by design.
• Every success, validation, auth, permission, not-found, conflict, rate-limit, and server-error branch is documented (§8).
• Every database read/write, cache invalidation, queue job, notification, and audit event is documented (§8 side effects, §11).
• Every route has examples for minimal request, full request, success response, and representative failures (§8).
• Every endpoint family has route, sequence, and error diagrams (§9).
• Every tradeoff and compatibility risk is documented (§13.5, §13.6).
• The API doc links to backend and features/flows (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/pos/backend
• Features and flows doc: /docs/developer/pos/feature
• TDD: not yet published