Orderverse DocsInvoice Pull & Status Refresh
Refresh the status of Xero-linked invoices — full refresh or incremental since a timestamp.
What invoice pull does
Invoice pull fetches the latest state of your Xero-linked invoices and updates the local record with:
- Current Xero status (Draft, Approved, Paid, Voided, etc.)
- Line item changes (quantity, unit price, description)
- Variance between the local version and the Xero version
Only invoices that have already been pushed and linked to Xero are included. Invoices that exist only in Xero (not in Orderverse) are not imported.
Prerequisites
Invoice pull has the same prerequisites as invoice push:
- Contacts synced and mapped
- Items synced and mapped
- Tax rates synced and mapped
Pull modes
Two modes are available:
| Mode | What it fetches |
|---|---|
| Since a timestamp | Only invoices modified in Xero after a chosen point in time |
| All linked | All invoices that have a Xero link, regardless of when last modified |
Use Since a timestamp for routine status refreshes — it is faster and avoids unnecessary API calls.
Use All linked when you need a full resync after a long gap or after making bulk changes in Xero.
Refreshing from the invoice list
- Go to Invoices.
- Select one or more linked invoices using the row checkboxes.
- Click Refresh Xero Status in the context action bar.
- Choose a time window:
| Option | Fetches invoices modified since… |
|---|---|
| Last watermark | The timestamp of the previous successful pull (default) |
| Last 15 minutes | 15 minutes ago |
| Last hour | 1 hour ago |
| Last 24 hours | 24 hours ago |
| Last 7 days | 7 days ago |
| Custom | Date and time you enter |
- Confirm to queue the pull.
Lookback limit
The maximum lookback period is 365 days. Custom dates older than 365 days are rejected.
Refreshing from the Xero menu
In the top navigation bar, the Xero icon opens a quick-access dropdown:
- Click the Xero icon in the header.
- Click Sync Invoices.
- The pull runs immediately using the last saved watermark — no dialog shown.
This is the fastest way to do a routine status refresh.
Refreshing a single invoice
- Open the invoice detail.
- Click Refresh Xero Status.
- The status updates for that invoice only.
Watermark
After each successful pull, the system saves a watermark — the timestamp of the latest Xero modification seen in that run. The next pull automatically uses this watermark as the starting point, so only genuinely new changes are fetched.
The current watermark is shown in the sync status table in Configuration → Integrations.
Variance
When a pulled invoice differs from the local version, a Variance badge appears on the invoice row and detail view.
| Variance level | Meaning |
|---|---|
| Variance | Minor differences — description, quantity, or unit price changed in Xero |
| High Variance | Structural differences — lines added/removed, tax types changed, status changed |
Variance is read-only in the current version. Review the differences and decide whether to update the local record manually.
Auto-apply for pending invoices
For invoices with pending status only, the system can automatically apply a safe subset of Xero changes without manual review:
| Change type | Auto-applied |
|---|---|
| Description updated | ✅ |
| Quantity changed | ✅ |
| Unit price changed | ✅ |
| Due date changed (if set by workspace rule) | ❌ Protected |
| Line items added or removed | ❌ Review required |
| Tax type changed | ❌ Review required |
| Item code changed | ❌ Review required |
| Status change | ❌ Review required |
Changes outside the safe subset are recorded as variance for manual review.
Batch limits
| Limit | Value |
|---|---|
| Invoice IDs per Xero API call | 100 |
| Maximum lookback period | 365 days |
Payment pending suppression
If a payment event has been recorded for an invoice within the last 5 minutes, the full diff-first pull for that invoice is deferred to avoid overwriting an in-flight payment update. A status-only refresh still runs.