Xero and BigCommerce integration

What moves between them

The primary flow runs from BigCommerce into Xero. As orders are placed and paid, ml-connector reads the order, its transactions, and any refunds and creates a matching ACCREC sales invoice in Xero, creating or updating the contact first so each invoice links to a valid customer, then recording the captured payment and applying credit notes for refunds. The reverse flow runs from Xero to BigCommerce: item price and description changes update the corresponding BigCommerce catalog products and variants by SKU. Order capture is event-driven on BigCommerce webhooks with a scheduled poll as catch-up, and catalog pushes run on the schedule you set.

How ml-connector handles it

ml-connector stores both credential sets encrypted, sends the BigCommerce X-Auth-Token on every store call, and runs the Xero OAuth flow per organization, refreshing the 30-minute access token from the refresh token before it expires and re-attaching the Xero-tenant-id header on each request. Because BigCommerce webhook payloads are stubs, each order or customer event triggers a fetch of the full record before it maps into Xero, and order SKUs are matched to Xero item codes so invoice lines and the catalog land on the right products. Xero has no idempotency-key header, so ml-connector anchors each web order to a stable InvoiceID and treats the write as an upsert to avoid duplicate invoices on retry, and BigCommerce refunds are processed one at a time per order since the API rejects concurrent refunds. Xero caps each organization at 60 calls per minute and 5,000 per day and BigCommerce returns HTTP 429 under load, so ml-connector backs off with jitter, honors the Retry-After and rate-limit reset headers, and uses If-Modified-Since with page paging to keep polling lean. BigCommerce webhooks auto-deactivate after about 48 hours of failures or 90 days idle, so a health check re-registers them, while a scheduled poll backfills anything a missed push dropped. Every record carries a full audit trail and can be replayed if a downstream call fails.

A real-world example

A mid-sized consumer goods retailer with roughly 60 staff sells through a BigCommerce store and keeps its books in Xero. Before the integration, a bookkeeper exported each day's web orders and re-typed them into Xero as sales invoices, mistyped customer details created duplicate contacts, and refunds processed in the store were missed in the ledger until month-end. With Xero and BigCommerce connected, paid orders post into Xero within minutes as ACCREC invoices against matched contacts, captured payments and refunds are recorded automatically, and Xero item and price updates push back to the catalog. The manual entry step is gone and the storefront and the books stay reconciled through the day.

What you can do

• •Create Xero ACCREC sales invoices from paid BigCommerce orders, with the contact matched or created first.
• •Record BigCommerce captured payments against Xero invoices and apply credit notes for refunds.
• •Push Xero item price and description changes to BigCommerce catalog products and variants by SKU.
• •Bridge the BigCommerce static X-Auth-Token and the Xero OAuth refresh-token flow, supplying the Xero-tenant-id on every call.
• •Capture orders on BigCommerce webhooks with a scheduled If-Modified-Since poll as catch-up, plus retries and a full audit trail.

Questions

Which direction does data move between Xero and BigCommerce?

Orders, payments, refunds, and shoppers move from BigCommerce into Xero as ACCREC sales invoices, payments, and contacts. Item price and description changes move the other way, from Xero out to the BigCommerce catalog. ml-connector matches contacts and SKUs on each pass so every invoice and catalog item lands on the correct record.

How does the integration handle Xero token expiry and the per-organization header?

Xero access tokens last 30 minutes and are refreshed from a 60-day refresh token, and every call must carry a Xero-tenant-id header that selects the organization. ml-connector refreshes the access token before it expires and re-attaches the correct tenant id on each request, so the connection keeps working without manual re-authorization unless the refresh token itself lapses after 60 days of disuse.

Does the integration rely on BigCommerce webhooks, and what about duplicate invoices?

Yes. BigCommerce pushes HMAC-signed webhooks for order and customer events, which ml-connector verifies and then uses to fetch the full record, since the payload is only a stub. Because Xero has no idempotency-key header, each web order is anchored to a stable InvoiceID and written as an upsert, so a retried or replayed event updates the existing invoice instead of creating a duplicate, and a scheduled poll backfills anything a deactivated webhook dropped.