Operations

Worker commands

Run one persisted operation locally:

pnpm --filter @accountingkit/server accounting:work

Dispatch pending outbox records to the configured queue backend:

pnpm --filter @accountingkit/server accounting:dispatch

Run the private HTTP worker used by the optional Cloud Tasks backend:

pnpm --filter @accountingkit/server accounting-worker

With ACCOUNTING_QUEUE_BACKEND=postgres and ACCOUNTING_EMBEDDED_WORKER_ENABLED=true, the normal serve command processes operations continuously in the API process. This is the Railway MVP mode and does not require a separate worker service.

The embedded worker also queues an invoice reconciliation for each active Xero connection every ACCOUNTING_RECONCILIATION_INTERVAL_MINUTES (15 minutes by default). Reconciliation uses the same payment-transition and signed customer-webhook path as a native Xero invoice webhook, so a missed provider delivery still produces invoice.payment_changed, invoice.paid, and the live-PDF refresh instruction. Scheduled runs use Xero's modified-since filter with a five-minute overlap; customers can trigger an unbounded safety-net scan immediately:

POST /v1/connections/{connection_id}/sync
Idempotency-Key: reconcile-invoices-2026-08-26T1200Z
Content-Type: application/json

{"scope":"invoices"}

Commercial operations

Create an effective-dated contract with commercial:set-contract, using an operator-supplied JSON payload. Generate an invoice-ready monthly statement with commercial:statement. Statements freeze the measured counts, included allowances, overages, currency, and total for review before invoicing.

Alerts

Monitor queued operation age, retry volume, dead-letter count, Xero 401/429/5xx responses, OAuth refresh failures, webhook delivery latency, KMS errors, and database saturation. Do not page on an individual provider retry; page when the retry budget, age objective, or tenant-wide error threshold is exceeded.

Recovery

Correct the root cause before replaying a failed or dead-letter operation:

POST /v1/operations/{operation_id}/replay
Idempotency-Key: replay-operation-1042
Content-Type: application/json

{"reason":"Xero connection was reauthorized"}

Failed customer webhook deliveries can also be replayed directly by delivery ID:

POST /v1/webhook-deliveries/{delivery_id}/replay
Idempotency-Key: replay-delivery-1042
Content-Type: application/json

{"reason":"Customer endpoint recovered"}

Replay preserves the original operation and successful step results, resets failed steps, and opens a fresh retry budget. The reason, actor, previous terminal state, and previous attempt count are written to the accounting audit log. Never edit usage events; create an explicit adjustment record or correct the generated statement through an operator-reviewed process.