Orderverse DocsInvoice Push
Push local invoices to Xero as draft invoices — single or batch, with preflight validation.
What invoice push does
Invoice push exports a local invoice to Xero as an ACCREC (Accounts Receivable) draft invoice. Once pushed, the invoice is linked to its Xero counterpart — future status updates can be pulled back automatically.
Each invoice is created once. Updating an already-pushed invoice is not supported in the current version.
Prerequisites
All three foundation syncs must be complete before any invoice can be pushed:
| Prerequisite | Why |
|---|---|
| Contacts synced & mapped | Invoice needs a matching Xero contact for the customer |
| Items synced & mapped | Every invoice line must map to a Xero item code |
| Tax rates synced & mapped | Every line tax type must resolve to a Xero tax type |
If any of these are missing, the invoice is blocked from pushing and shows a specific error code. See Troubleshooting for recovery steps.
Pushing a single invoice
- Open the invoice detail from the Invoices list.
- Click Push to Xero.
- The system runs a preflight check — any blocking issues are shown before the push proceeds.
- Confirm to queue the push.
Status updates in the invoice detail as the push completes.
<!-- screenshot: Invoice detail showing Push to Xero button and status -->Pushing multiple invoices (batch)
- Go to Invoices.
- Select one or more invoices using the row checkboxes.
- Click Push to Xero in the context action bar.
- A preview dialog shows:
| Count | Meaning |
|---|---|
| Eligible | Ready to push — all prerequisites met |
| Blocked | Missing contact / item / tax mapping |
| Already linked | Previously pushed — skipped |
- Review the counts and confirm.
- Eligible invoices are queued. Blocked invoices are skipped and listed with their reason.
Batch limits
| Limit | Value |
|---|---|
| Maximum invoices per batch request | 50 |
| Maximum concurrent pushes | 5 |
If you select more than 50 invoices, split the selection into multiple batches.
What is sent to Xero
Each pushed invoice creates a Xero draft with:
| Field | Value |
|---|---|
| Type | ACCREC (Accounts Receivable) |
| Status | DRAFT |
| Invoice Number | Local invoice number |
| Due Date | From local invoice |
| Contact | Matched Xero contact |
| Line Items | SKU, quantity, unit price, tax type, description |
Note:
LineAmountis intentionally omitted from the payload. Xero calculates line totals itself to avoid silent rounding discrepancies.
Per-invoice preflight checks
Before each push (single or batch), the system validates:
| Check | Blocks push if… |
|---|---|
| Contact mapping | Customer has no linked Xero contact |
| Item mapping | Any invoice line has no linked Xero item code |
| Tax mapping | Any line tax type has no mapped Xero tax type |
| Freight | Freight is set to TBC (manual) and not yet finalised |
Idempotency & duplicate prevention
Each push is identified by a deterministic key based on the invoice ID and payload. If the same push is retried after a network failure, Xero receives the same key and does not create a duplicate invoice.
If the invoice content changes before a retry, a new key is generated and a new Xero invoice is created.
After pushing
Once pushed successfully:
- The invoice shows a Linked badge with the Xero invoice ID.
- Status can be refreshed using Invoice Pull.
- The invoice cannot be pushed again — it is already linked.