Skip to main content
Order submission is triggered from the payment flow when the balance due reaches zero and the user taps Done.

​
Architecture

​
posReference format

Example: NU/CFG1/S42/1709123456789-3f7a The posReference is generated once and persisted before submission. Retries use the same reference for idempotency — Odoo returns the existing order if the reference is already known.

​
Submission flow

When hub sync is active, orders are finalized through the hub first. The hub calls hub_finalize_snapshot on Odoo, which runs the full fiscal pipeline (create_from_ui) inside a database savepoint. If the hub path fails for any reason, the frontend falls back to the direct API automatically.
1

Validate

Check that bootstrapState has valid config_id and session_id.
2

Choose path

If hub sync is active (transport.mode === "hub") → Hub finalization via transport.finalizeOrder(). Otherwise → Direct API (/orders/create or /orders/update).
3

Map payload

  • product_id strings → integers
  • tax_ids strings → integers
  • Payment lines include statementId, journalId, accountId, amount, and name (payment method name)
  • amountPaid (tendered) + amountReturn (cash change)
4

Submit

Hub path: Sends a full OrderSnapshot (lines, totals, payment lines) to the hub, which forwards to Odoo’s hub_finalize_snapshot. On failure, falls back to the direct API automatically.Direct path: POST to /orders/create or /orders/update.
5

Handle result

  • Success: local order marked paid, table freed, redirected to floor plan
  • no_pos_session: triggers global session guard (redirects/locks)
  • Other error: payment screen stays open, user can retry

​
Hub finalization backend

The hub_finalize_snapshot method on pos.order wraps create_from_ui in a database savepoint. If any part of order creation fails (e.g., payment processing), the entire operation rolls back atomically — no phantom draft orders are left behind. Key behaviors:
  • Default partner: When no customer is selected, config.default_partner_id is used (typically “CLIENTE DE CONSUMO 1”), ensuring the receivable account is available for payment processing.
  • Idempotency: If an order with the same pos_reference already exists and is paid, the existing order is returned.
  • Payment verification: After create_from_ui, the method verifies that statement_ids were actually created. If not, the savepoint rolls back.
  • Fiscal pipeline: The full NCF/DGII fiscal pipeline runs inside create_from_ui, so hub-finalized orders get the same fiscal treatment as direct API orders.

​
Payment mapping

​
Usage

​
Backend mode

The mode field on the request defaults to order when omitted. Other values: return (refund) and payment (invoice collection). See src/api/orders/types.ts for full request/response type definitions.