Wave Accounting and Orderful integration

What moves between them

The primary flow runs from Wave to Orderful. Wave invoices are pulled via GraphQL webhook triggers (invoice.created, invoice.updated, invoice.paid) and translated to X12 810 EDI documents mapped to the Orderful account for each customer. Orderful purchase order documents (850 EDI) are received via Orderful webhooks and translated back to Wave transactions, creating a corresponding entry in Wave's transaction ledger for each order received. Customer data flows one direction only: Wave customers are mapped to Orderful ISA identifiers on setup, and the mapping is maintained in ml-connector's connection table. Purchase orders received from EDI do not create Wave customers.

How ml-connector handles it

ml-connector bridges two different authentication schemes by storing both the Wave OAuth refresh token and the Orderful API Key encrypted, then presenting the correct credential on each request: the OAuth token (refreshed every 2 hours) for Wave GraphQL calls, and the static API Key for Orderful REST calls. It subscribes to Wave invoice webhooks (invoice.created, invoice.updated, invoice.paid) and validates the HMAC-SHA256 signature on each webhook within the 5-minute replay window. When an invoice event arrives, ml-connector pulls the full invoice and customer data from Wave via GraphQL, maps the Wave customer to the corresponding Orderful ISA identifier using the stored mapping, and POSTs an 810 EDI document to Orderful /v4/inbox specifying the target ISA receiver and the test or live stream per environment. For inbound purchase orders, ml-connector either receives Orderful webhooks (850 documents pushed to a public endpoint) or polls /v3/polling-buckets every 10 minutes (up to 100 docs per request). Each 850 is translated to a Wave transaction with the sender ISA mapped back to a Wave customer, and the PO details (line items, amounts) are posted to Wave's transaction endpoint. Wave does not support PATCH operations on invoices, so updates are handled by creating a credit memo (812) and a new invoice (810) in Orderful to represent the change. ISA identifier mapping is manual on setup (Wave customer ID to Orderful ISA ID) and stored per connection; mismatches cause invoices to route to the wrong trading partner or fail with a 400 from Orderful until corrected.

A real-world example

A small contract manufacturer uses Wave Accounting to manage invoicing and expenses. Its three largest customers require invoices in X12 EDI format sent through Orderful's network. Before the integration, the accounting team manually exported invoices from Wave, reformatted them as EDI documents, and uploaded them to Orderful every time an invoice was created or updated. Mistakes in mapping customer names to EDI identifiers led to invoices routing to the wrong trading partner. When purchase orders arrived from customers via EDI through Orderful, the team downloaded them, re-entered them into Wave by hand, and reconciled line items against their actual shipments. With Wave and Orderful connected, each new invoice in Wave automatically translates to an EDI 810 document and routes to the correct trading partner via Orderful. Incoming purchase orders flow back into Wave without re-keying, so the accounting team can reconcile shipments against actual orders in one system.

What you can do

• •Translate Wave invoices to X12 810 EDI documents and send them to Orderful-connected trading partners on invoice creation, update, or payment.
• •Receive X12 850 purchase orders from Orderful partners and post them as Wave transactions, mapping EDI identifiers to Wave customers.
• •Map Wave customers to Orderful ISA identifiers so invoices and purchase orders route to the correct trading partner.
• •Authenticate Wave with OAuth 2.0 token refresh and Orderful with static API Key, bridging both platforms in a single connection.
• •Handle Wave invoice updates by issuing credit memos and replacement invoices in EDI, with full retry logic and audit trail for every document.

Questions

How does ml-connector handle Wave invoices that are updated after being sent to EDI?

Wave invoices cannot be patched after creation. When an existing Wave invoice is updated (new line items, price changes), ml-connector issues a credit memo (812) in Orderful to reverse the original invoice and then sends a new invoice (810) with the updated details. Both documents route to the same trading partner ISA identifier so the partner can reconcile the correction.

What happens if a Wave customer has no ISA identifier mapping in Orderful?

ml-connector requires a stored mapping from each Wave customer ID to an Orderful ISA identifier. If a customer is missing from the mapping, the invoice cannot be routed and ml-connector returns a 400 error on the Orderful POST. The mapping is set up once per connection and stored encrypted; it must be updated manually if new Wave customers are added.

Can ml-connector receive EDI documents from Orderful if Wave is not exposing a public webhook endpoint?

Yes. If your Wave instance cannot receive webhooks, ml-connector can poll Orderful every 10 minutes using /v3/polling-buckets to retrieve up to 100 documents per request. The polling fallback means you do not need a public endpoint, but documents will be delayed up to 10 minutes compared to webhook push.