POS Service API
Stores, registers, shifts, catalog, sales, refunds, offline sync, and owner reporting
The POS Service powers the 505pay register experience — the tablet-first
Flutter app at pos.505pay.link and any third-party integrator running their
own front-of-house terminal. It exposes a stable HTTP surface for the entire
operational loop: bring up a store, open a shift, scan a catalog, take payment,
print a receipt, and reconcile the day at close.
Base URLs
| Environment | Hostname |
|---|---|
| Sandbox | https://sandbox.505pay.link |
| Production | https://api.505pay.link |
All endpoints require an Authorization: Bearer <jwt> issued by the
Auth Service. The JWT must carry the pos.* permissions
that match the caller's role (typically pos.cashier, pos.shift_manager,
or pos.owner).
Domain model
A real-world store is modeled as a small hierarchy. Each level isolates state so two registers at the same store can take sales independently and reconcile cleanly at end-of-day.
- Store — physical location. Owns the catalog and the staff roster.
- Register — a single point-of-sale device bound to a store.
- Shift — the open/close session for a register; every sale rolls up to exactly one shift so cash-drawer math always balances.
- Sale — a single transaction. Carries one or more line items, a payment method (often a 505pay payment intent), and a printable receipt.
- Refund — issued against a prior sale; mirrors the original payment method via the Payments service.
A day in the life
Idempotency & offline sync
- Sale creation accepts an
Idempotency-Keyheader. The same key replays the original response without double-charging. See the Idempotency guide. - Tablets running offline buffer sales locally and replay them via
POST /synconce connectivity returns. The endpoint accepts a batch of pending operations and returns per-op success/conflict status.
Cash-drawer integrity
Once a shift is closed it is immutable. Mistakes go through the
exceptions queue, not by re-opening the shift.
Endpoint reference
Stores
Create and manage physical store locations.
Registers
List registers (terminals) associated with stores.
Shifts
Open, track, and close cashier shifts with float reconciliation.
Catalog
Search SKUs, create products, and process cart checkout.
Sales & refunds
Create sales, fetch details, issue refunds, and print receipts.
Customers
Look up and search customer profiles by phone number.
Offline sync
Replay a batch of offline sales and shift events after connectivity is restored.
Exceptions & owner reporting
Review unresolved exceptions and fetch owner-level KPI snapshots.
Retail analytics
Rollup reports by cashier, category, SKU, and hourly heatmap.
Ungrouped operations
84 operations in the spec are not listed in the groups file. Add their operationIds to content/docs/api/pos.groups.json.
List product categories for the tenant
List all modifiers for the tenant (flat, across all variants)
List catalog products (management workspace)
Get a single product (management workspace)
Server-Sent Events stream of catalog changes
List tax categories for the tenant
List modifiers attached to a variant
List voucher / coupon codes
Receipt-delivery capability flags (AC-30.3)
List low-stock alerts (paginated)
Dashboard widget summary (open_count + last_scan_at)
Get the active inventory-valuation method
List station options for the KDS station picker
List KDS tickets for a station
List purchase orders
Get purchase order with lines
List POS cross-outlet consolidated report
Exception report (voids + discounts)
Per-variant gross-margin report
Get POS HQ cross-outlet dashboard
Kartu stok — per-item stock movement card
Payment-method breakdown report
Get POS tax-summary report (DPP / PPN / PB1 per category)
Persediaan valuation — on-hand value per variant/store
List a shift's cash drawer movements
X-report (mid-shift snapshot) for an open shift
Z-report (end-of-day summary) for a closed shift
Z-report as printable PDF
List stock-count adjustment movements
Get per-outlet anti-fraud control config
Get per-outlet cash-rounding config
Get per-outlet F&B service-charge config
List suppliers
Get supplier by id
List tables for a store
Get a table by id
List inter-store transfers
Get transfer with lines
Create a product category
Upload a product image (multipart)
Bulk import products from a multipart CSV upload
Bulk import products from raw CSV
Create a tax category
Create a modifier on a variant
Create a voucher / coupon code
Create an open (unpaid) parent order
Bind an existing order to a table
Send an order to the kitchen (creates / returns a KDS ticket)
Claim a short code from a terminal device
Generate a 6-hex short code for a KDS or customer-display terminal
Create a payment-link intent from a POS cart (AC-4.4)
Set or rotate the caller's cashier PIN
Verify a candidate PIN for the caller
Create draft purchase order
Cancel a draft or submitted PO
Receive a submitted purchase order (atomic cascade)
Submit a draft purchase order
Send a receipt by email (AC-30.3 / AC-CO-1)
Send a receipt by SMS (AC-30.3 / AC-CO-2)
Void a completed POS sale and release reserved stock
Split a pending sale into child orders
Record a non-sale cash drawer movement
Record a no-sale (Buka Laci) drawer-open
Submit physical stock count (manager-only)
Create supplier
Create a table for a store
Create draft inter-store transfer
Cancel a draft or in_transit transfer
Complete a transfer (atomic dual-leg movements)
Preview a voucher against an order
Set the inventory-valuation method (versioned, audited)
Update per-outlet anti-fraud control config
Update per-outlet cash-rounding config
Update per-outlet F&B service-charge config
Update supplier
Partially update a product
Partially update a tax category
Partially update a variant (currently reorder_point only)
Update a KDS ticket's status
Update a table's label/capacity/status
Soft-delete a product
Soft-delete a tax category
Expire / soft-delete a voucher
Delete supplier (rejected if referenced by PO)
Was this page helpful?