POS

Read Conventions first.

pos_terminals

• id, business_id, branch_id NOT NULL
• default_warehouse_id NOT NULL
• code - UNIQUE (business_id, code); name
• api_key_hash NOT NULL - opaque token, SHA-256 hashed
• app_version DEFAULT ‘’ - self-reported on Ping
• last_seen_at NULL
• is_active, created_by, created_at

pos_sales

Links a terminal sale to the A/R Invoice and payment it produced. Idempotent on the terminal’s own id.

• id, business_id, terminal_id NOT NULL
• client_sale_id uuid NOT NULL - UNIQUE (business_id, client_sale_id) - the offline outbox row’s id, making sync idempotent
• terminal_code, terminal_sale_no
• ar_invoice_id NOT NULL
• incoming_payment_id NULL
• cashier_user_id NULL
• source_ar_credit_memo_id NULL - an “exchange” is represented by a populated source id, not a flag
• first_scan_at NULL
• created_at; indexes (terminal_id, created_at), (ar_invoice_id)

pos_invoice_reservations

Real A/R invoice numbers reserved up front so a cashier sees the number from the first scanned item, even offline. An unconsumed reservation is marked ‘cancelled’, not deleted - the resulting gap in the sequence is expected, and this table is what the Cancelled Bills report reads to explain each gap.

• id, business_id, branch_id NOT NULL, terminal_id NOT NULL
• document_no - UNIQUE (business_id, document_no)
• status DEFAULT ‘reserved’ - CHECK IN (‘reserved’,‘used’,‘cancelled’)
• reserved_at, used_at, cancelled_at
• ar_invoice_id NULL, cashier_user_id NULL, cancel_reason
• Index (terminal_id, status)

pos_void_events

One row per supervisor-authorized Void / Cancel / Discount action at a terminal.

• id, business_id, terminal_id NOT NULL
• client_event_id NOT NULL - UNIQUE (business_id, client_event_id) (idempotent sync)
• event_type - CHECK IN (‘line_void’,‘bill_cancel’,‘net_discount’,‘line_discount’)
• cashier_user_id NULL; authorized_by_user_id NOT NULL
• invoice_reservation_id NULL - set for a bill_cancel
• customer_id NULL
• item_name, quantity NULL, amount DEFAULT 0, reason
• lines_json jsonb NULL - the cancelled/returned lines, used to build the cancelled ar_invoices record
• Fraud signals: tendered_amount NULL - non-null only when the cashier had typed a value into the Cash modal before backing out and voiding; a near-deterministic fraud signal; cart_total_before, cart_item_count_before - review context only
• created_at
• Indexes (business_id, event_type, created_at DESC); partial (business_id, cashier_user_id, created_at DESC) WHERE tendered_amount IS NOT NULL

pos_cash_movements

Cash In / Cash Out (“Paid Out”) ledger. Cash Out is the guarded direction.

• id, business_id, terminal_id NOT NULL
• client_movement_id - UNIQUE (business_id, client_movement_id)
• movement_type - CHECK IN (‘cash_in’,‘cash_out’)
• cashier_user_id NULL; authorized_by_user_id NULL - set for cash_out only
• amount - CHECK > 0
• reason; denominations jsonb NULL - note breakdown, physically removed (cash_out only)
• created_at; index (terminal_id, created_at)

pos_register_sessions

One row per till session, upserted at open and at close. cash_sales/cash_in/cash_out/expected_cash/ cash_difference are computed server-side at close from real data - never trusted from the terminal’s own totals.

• id, business_id, terminal_id NOT NULL
• client_session_id - UNIQUE (business_id, client_session_id)
• cashier_user_id NULL
• opening_cash DEFAULT 0; opened_at NOT NULL
• closing_cash NULL; closed_at NULL
• status DEFAULT ‘open’ - CHECK IN (‘open’,‘closed’)
• denominations jsonb NULL
• cash_sales, cash_in, cash_out, expected_cash, cash_difference NULL (server-computed)
• actual_card_sale NULL - optional cashier-entered card-terminal total, for a Card Sale Difference
• force_closed DEFAULT false - closed by super admin master password, not a real Z Reading
• X Reading (mid-shift check that does not close the till): x_reading_at, x_reading_by, x_reading_declared_cash, x_reading_denominations, x_reading_actual_card_sale, x_reading_system_cash_in_hand, x_reading_system_card_sales
• Index (terminal_id, status)