Oracle NetSuite and Avalara integration

What moves between them

The primary flow runs from Oracle NetSuite into Avalara and back. When a NetSuite invoice or sales order is created or edited, ml-connector reads it and posts it to AvaTax CreateTransaction with its lines and addresses, then writes the calculated tax amount back onto the NetSuite record. Vendor bills are sent as PurchaseInvoice transactions so Avalara self-assesses use tax. Reference data moves alongside: NetSuite items map to AvaTax tax codes and NetSuite customers map to AvaTax customer records and exemption certificates. The cadence is event-driven where NetSuite Event Subscriptions are enabled, with a scheduled SuiteQL poll backfilling any document a push missed. Avalara is the tax engine, so no financial records flow from Avalara back into NetSuite beyond the tax figures.

How ml-connector handles it

ml-connector stores both credential sets encrypted. For Oracle NetSuite it signs a JWT with the customer's private key, exchanges it at the account-specific token endpoint, and refreshes the 60-minute access token when a call returns 401; it also accepts the account ID per customer since NetSuite has no shared host. For Avalara it sends the account ID and license key as HTTP Basic on every request. Each NetSuite transaction id is reused as the AvaTax document code, and CreateOrAdjustTransaction is used so a retry updates the uncommitted document in place rather than recording tax twice; once committed, that code is reserved. Addresses are pre-checked with the AvaTax resolve endpoint because an invalid address fails the calculation, and items must carry the correct tax code or taxable goods can read as exempt. NetSuite Event Subscriptions arrive without a signature, so the listener is protected by IP allowlist and a shared secret and treated as idempotent because retries can deliver twice. Both sides return HTTP 429 when rate limited, so ml-connector backs off with jitter, and a NetSuite sandbox refresh clears the M2M certificate, which it tracks so a cleared mapping does not become a silent outage. Every record carries a full audit trail and can be replayed.

A real-world example

A mid-sized online retailer running Oracle NetSuite for order management and finance sells into roughly thirty states and had been maintaining tax rates by hand and reconciling under-collected tax at filing time. Sales tax on each invoice was estimated from a static rate table that drifted out of date as nexus rules changed, and exemption certificates lived in a spreadsheet the billing team checked manually. With Oracle NetSuite and Avalara connected, every invoice is priced for tax by AvaTax at creation using the validated ship-to address and the item's tax code, and exempt customers are recognized automatically from their linked certificate. The finance team stops curating rate tables, and the tax recorded in NetSuite matches what Avalara will report at filing.

What you can do

• •Calculate sales tax on Oracle NetSuite invoices and sales orders through AvaTax and write the result back to the record.
• •Send NetSuite vendor bills to Avalara as PurchaseInvoice transactions so use tax is self-assessed.
• •Map NetSuite items to AvaTax tax codes and NetSuite customers to AvaTax exemption certificates so the calculation is correct.
• •Bridge NetSuite OAuth 2.0 certificate-based authentication with Avalara HTTP Basic account ID and license key.
• •Trigger on NetSuite Event Subscriptions with a scheduled SuiteQL backfill, retries, and a full audit trail on every record.

Questions

Which direction does data move between Oracle NetSuite and Avalara?

NetSuite is the system of record and Avalara is the tax engine. ml-connector reads each NetSuite invoice, sales order, or vendor bill, posts it to AvaTax for calculation, and writes the returned tax back onto the NetSuite record. No financial documents flow from Avalara into NetSuite, because AvaTax holds no invoices, vendors, or GL accounts of its own.

How are the two different authentication methods handled?

Oracle NetSuite uses OAuth 2.0 Client Credentials, a certificate-based flow where ml-connector signs a JWT with the customer's private key and exchanges it for a 60-minute token at the account-specific endpoint. Avalara uses HTTP Basic with an account ID and license key. ml-connector stores both encrypted, refreshes the NetSuite token on a 401, and sends the Avalara Basic header on every call.

How does the integration avoid recording tax twice on a retry?

AvaTax uses the document code on a transaction as its idempotency key. ml-connector reuses each NetSuite transaction id as that code and calls CreateOrAdjustTransaction, so resending an uncommitted document updates it in place instead of creating a duplicate. Once a transaction is committed its code is reserved, so a replay cannot overwrite recorded tax.