Xero/Netsuite ERP Sync

Paid pluginsize Lplanned, not built

Indicative price, not an offer: €59/mo; credential: we maintain ERP API, daily reconciliation

Generated from docs/plan/paid/xero-netsuite-erp-sync/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

Accounting teams sync AstroBaaS orders with Xero or NetSuite, creating invoices, journal entries, and reconciliation records automatically. The paid pack maintains ERP vendor integrations and GL mapping; core owns the order-to-invoice interface.

The problem

Accounting must manually enter AstroBaaS orders into Xero or NetSuite every day. Errors propagate through reconciliation. Two-way sync is needed to match GL accounts, payment status, and refunds.

What it does

• Order-to-invoice: new AstroBaaS orders create invoices in Xero/NetSuite with correct GL account mapping
• Payment sync: when an AstroBaaS payment is received, invoice is marked paid in ERP
• Refund sync: refunds create credit notes in ERP automatically
• GL account mapping: admin configures which GL account receives revenue, tax, discounts, shipping
• Tax calculation: sync includes tax amounts and tax codes for ERP reporting
• Reconciliation report: daily report showing orders synced, failed syncs, GL balances
• Test mode with mock ERP responses
• Audit log: every sync event

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• Expense tracking: we sync revenue and refunds only; merchant’s expense reports are handled outside AstroBaaS.
• Budget forecasting: ERP may have budget modules; AstroBaaS does not predict future revenue.
• Intercompany transactions: if merchant has multiple legal entities, ERP handles consolidation; AstroBaaS syncs one entity only.
• Complex GL hierarchies: we support standard GL structure (revenue, tax, discounts, shipping); custom GL segments are merchant’s responsibility.

Data model

New document type: erp_sync_record { orderId, invoiceId (ERP-issued), glMappings { revenue, tax, discount, shipping }, syncedAt, lastError }. New settings: erp_gl_account_revenue, erp_gl_account_tax, erp_gl_account_discount, erp_gl_account_shipping (all integers).

API

• POST /api/erp/sync-order { orderId } (called by scheduler or manually)
• GET /api/erp/sync-status?from=2026-09-01&to=2026-09-03 (admin only) -> list of synced orders
• POST /api/erp/gl-mapping { revenue, tax, discount, shipping } (admin only)
• GET /api/erp/reconciliation?date=2026-09-03 (admin only) -> GL balances vs. AstroBaaS totals

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Admin sees: ERP connection status, GL account mapping editor, daily sync report with success/failure counts, reconciliation variance (GL balance vs. AstroBaaS total), manual sync button, sync error log.

The seam — why this is paid

Core owns the order-to-invoice interface and GL structure. Paid pack owns: Xero/NetSuite API adapters, GL mapping strategy, ERP vendor support relationship.

Credential: ERP vendor integration (Xero, NetSuite), GL mapping, audit trail

Dependencies

• order subsystem (existing; provides order data)
• payment subsystem (existing; provides payment status)
• scheduler subsystem (existing; runs sync jobs)

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• An AstroBaaS order for 100 EUR with 19 EUR tax creates an invoice in Xero with correct GL accounts
• When the order is paid in AstroBaaS, the Xero invoice is marked paid
• A refund in AstroBaaS creates a credit note in Xero
• Admin configures GL accounts: revenue=4000, tax=2100, discount=5000, shipping=4100; new order uses these accounts
• Daily reconciliation report shows GL revenue balance vs. AstroBaaS revenue total; variance is zero if all orders synced
• A sync error (ERP API timeout, invalid GL account) is logged with timestamp and action; sync is retried
• In test mode, order sync returns mock invoice ID; no real ERP records are created
• Audit log shows order 12345 synced to Xero invoice INV-001 at 2026-09-03 10:15

Risks

If GL accounts are mapped incorrectly, revenue is posted to the wrong accounts and reconciliation fails. If payment sync is one-way, AR aging becomes incorrect in ERP. If refunds are not reversed, GL becomes unbalanced. If tax amounts are rounded differently, reconciliation shows small variances every month. If sync order is wrong (refund before payment received), GL goes negative temporarily.

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.