Wave Accounting and Chargebee integration

What moves between them

Customer records and invoices flow from Wave Accounting into Chargebee on a two-way sync. Customers created or updated in Wave are synced into Chargebee as billing accounts, and invoices created or approved in Wave are written to Chargebee as subscription invoices mapped to the matching customer. Invoice.paid events trigger updates in Chargebee to mark invoices as collected. Transactions and payment data flow in the same direction. The sync respects Wave's 2-hour OAuth token refresh cycle and listens for Wave webhooks to detect changes in real time rather than polling.

How ml-connector handles it

ml-connector stores Wave OAuth credentials and manages token refresh automatically before the 2-hour expiry window. It receives Wave webhooks for customer and invoice changes, validates signatures with HMAC-SHA256 and the Wave x-wave-signature header, and queues the events. For each event, it reads the full entity via Wave's GraphQL API to obtain complete data (Wave webhooks emit IDs only, not full payloads), then maps the customer or invoice into Chargebee's data model and POST to the Chargebee REST API using basic auth. It respects Chargebee's rate limits by monitoring response codes and backing off on 429; it also handles Chargebee's pagination for any reads of existing Chargebee records. Every record carries an idempotency key so that webhook retries or replays do not create duplicate billing records. Failed writes are queued for retry with exponential backoff.

A real-world example

A small SaaS company uses Wave Accounting to manage invoices, customers, and bookkeeping, and Chargebee to handle recurring subscription billing and payment collection. Before the integration, finance exported customer lists from Wave each month and manually created matching accounts in Chargebee, and invoices created in Wave were re-entered into Chargebee by hand to ensure billing and accounting records stayed in sync. After Wave and Chargebee are connected, new customers created in Wave appear automatically in Chargebee, and invoices approved in Wave flow directly into the subscription billing system. Month-end reconciliation is faster because customer counts and invoice totals already match between the two systems without manual re-entry.

What you can do

• •Sync Wave Accounting customers into Chargebee as subscription billing accounts.
• •Automatically write Wave invoices to Chargebee when they are created or approved.
• •Refresh Wave OAuth 2.0 tokens on the standard 2-hour expiry cycle to prevent auth failures.
• •Validate Wave webhook signatures using HMAC-SHA256 and replay detection.
• •Apply Wave invoice payments and customer updates to Chargebee with idempotency keys and retry logic.

Questions

How does ml-connector handle Wave's GraphQL API and Chargebee's REST API?

ml-connector reads from Wave's GraphQL endpoint at https://gql.waveapps.com/graphql/public and queries customer and invoice data in response to webhook events. It then transforms the Wave schema into Chargebee's REST model and writes to Chargebee's /api/v2/ endpoints using HTTP Basic Auth. Wave webhooks trigger the sync in real time, so polling is not required on Wave's side.

What happens when Wave OAuth tokens expire?

Wave OAuth access tokens expire after 2 hours. ml-connector automatically refreshes the token before the expiry window using the stored refresh token, so API calls never fail due to token age. Token refresh happens transparently without pausing the sync.

How are Wave and Chargebee records matched when syncing?

ml-connector stores a mapping table of Wave customer IDs to Chargebee customer IDs after the first sync. On subsequent updates, it looks up the matching Chargebee record and updates the existing account or invoice rather than creating duplicates. Each write includes an idempotency key derived from the Wave record ID, so accidental webhook retries do not duplicate billing records.