Sync & push flows
Nudge moves data in two directions: inbound sync pulls debtors, invoices, and payments from your ERP, and outbound push sends dispatched invoices and applied payments back. This page explains what triggers each flow and what your middleware should expect.
Inbound sync (ERP → Alderstone)
Sync is pull-based: Alderstone calls your middleware's list endpoints in a fixed order: debtors first (so invoices can link to them), then invoices, then payments.
Triggers
- Initial connect. For native connections, the connect callback runs a full contacts → invoices → payments import. For REST connections, saving the connection runs the health check only; the first import happens on the next manual or scheduled sync.
- Manual. The sync toolbar in Settings runs the pipeline on demand, useful after fixing a middleware issue.
- Scheduled. A nightly job (around 02:00 UTC when configured) runs for all active native and REST connections.
Full vs incremental sync
The first sync omits modifiedSince, so your middleware should return the complete data set (paginated). Subsequent syncs pass modifiedSince as an ISO datetime; return only records created or changed after that point. If your ERP can't filter by modification time, returning the full set is safe but slower; Alderstone deduplicates by ERP identifier.
Pagination
List endpoints receive page and limit, and Alderstone keeps requesting pages until your response says hasMore: false. Large tenants should expect the nightly sync to page through the whole data set; keep per-page latency low instead of returning giant pages.
Outbound push (Alderstone → ERP)
Push happens immediately on the triggering event, using the active connection (native preferred when both exist):
| Event | REST endpoint |
|---|---|
| Invoice dispatched | POST /invoices/push |
| Cash application approved | POST /payments/push |
Idempotency
Alderstone skips duplicate pushes for invoices and payments that were already pushed successfully. Your middleware should still be defensive: if a retry does arrive for an invoice that already exists in the ERP, return the existing erpInvoiceId instead of creating a duplicate.
What to expect operationally
- No inbound webhooks. All integration is request/response initiated by Alderstone; your middleware never calls Alderstone.
- Partial failures fail the sync. If a list endpoint errors mid-sync, the connection status becomes FAILED. Fix the middleware issue and use Sync now to recover.
- Push has prerequisites. Invoice push needs the debtor to be linked (an
erpDebtorIdfrom a prior sync); payment push needs the invoice to already exist in the ERP. See Troubleshooting.
Edge cases
| Case | Behaviour |
|---|---|
| Debtor missing on invoice import | Alderstone creates the debtor from the invoice's contact fields |
| Payment doesn't match any invoice | Payment is skipped; check middleware logs for the identifiers involved |
| Token expired (native OAuth) | Alderstone auto-refreshes; the user is asked to re-authenticate only if refresh fails |
| 401 from REST middleware | Connection status becomes FAILED; rotate the key or fix middleware config, then Sync now |