What is synced
Rolled-up invoices that bill one payer for several serviced customers keep each customer’s lines grouped, so the NetSuite invoice reads the same way the Alguna one does. See Rollup billing.
If an invoice with the same document number already exists in NetSuite — for example one keyed by hand before the connector was enabled — Alguna adopts it rather than creating a duplicate.
Setting up
Authentication is certificate-based. Alguna issues a certificate, you register it in NetSuite against a dedicated integration record, and NetSuite returns an ID that completes the connection. You and Alguna each own part of the setup:
You’ll need the Integration Manage permission in Alguna, and an Administrator login for the NetSuite account you’re connecting.
Before you start
Your NetSuite account needs a few records in place before Alguna can connect. If Alguna has already prepared your account, skip ahead to step 1.NetSuite records your administrator creates
NetSuite records your administrator creates
Find the account ID. Go to Setup → Company → Company Information and copy the Account ID. A sandbox account ID ends in a suffix, for example
1234567_SB1. Enter it exactly as shown. There’s no separate environment field, because the suffix identifies the sandbox.Enable the required features. Go to Setup → Company → Enable Features:Alguna reads your lists through the SuiteQL query service, which is why SuiteAnalytics Workbook belongs here and in the role below.Create a dedicated integration role. Go to Setup → Users/Roles → Manage Roles → New and name it
Alguna Integration Role.Give it these permissions:
Three of these are worth calling out:
- Customers must be Full, not View. With View only, NetSuite hides the write operations and customer creation fails
- SuiteAnalytics Workbook is what lets Alguna read your lists. Subsidiaries, currencies, items, classes, accounts, tax codes, and amortization templates all come back through SuiteQL, as does the lookup that matches an existing invoice, and NetSuite refuses those queries without this permission
- Log in using OAuth 2.0 Access Tokens at Full level is what every token request depends on, and it’s the most common cause of a failed connection
Alguna Integration. Check Give Access and assign only the Alguna Integration Role.Don’t reuse a real person’s employee record, because a deactivation or a role change breaks the connection. Don’t assign the Administrator role.Create the integration record. Go to Setup → Integration → Manage Integrations → New and name it Alguna.- Set State to Enabled
- On the Authentication tab, check OAuth 2.0, then Client Credentials (Machine to Machine) Grant
- Under Scope, check REST Web Services
- Leave Token-Based Authentication and the user-credential options unchecked
Step 1: Connect Alguna and NetSuite
This step moves between the two systems. Alguna issues the certificate, NetSuite takes it and returns an ID, and Alguna verifies the result.1
Start the connection in Alguna
Go to Integrations, click Connect on the NetSuite tile, enter your Account ID and Client ID, then click Continue.
2
Download the certificate
Click Download certificate. The
.pem file holds public certificate material only, and Alguna generates and keeps the private key. Leave the wizard open.3
Upload the certificate to NetSuite
Go to Setup → Integration → Manage Authentication → OAuth 2.0 Client Credentials (M2M) Setup → Create New, and fill in:
Save, then copy the new Certificate ID.On macOS, if the file chooser hides the downloaded
.pem, open the Downloads folder directly or press Cmd+Shift+. to show hidden files.4
Verify the connection in Alguna
Paste the Certificate ID back into the wizard and click Verify & connect.
- The role is missing Log in using OAuth 2.0 Access Tokens at Full level
- The integration record isn’t Enabled, or the REST Web Services scope is off
- The M2M mapping points at a different role or application
- A typo in the account ID, the client ID, or the certificate ID
Verification proves authentication only. It doesn’t prove that the role can read and write the records it needs, so a wrong permission shows up at the first sync rather than here.
Step 2: Map legal entities to subsidiaries
On the connected NetSuite card, click the gear icon to open Configure, then go to the Direct sync tab. For each Alguna legal entity that belongs in NetSuite:- Select its NetSuite subsidiary
- Turn the sync switch on
- Click Save
Step 3: Send Alguna your product mapping
Alguna needs to know which NetSuite item and class to put on each invoice line. Send your Alguna contact the mapping below, and we’ll configure it for you. For each product in your catalog:- The NetSuite item it maps to
- The class it posts to, which stays the same across every region
- Any regional item differences, if a product uses a different item depending on where the buyer is
EU bucket covering the EU member states. A country can belong to only one bucket. Every product also needs a fallback item for buyers outside any bucket you define.
Two lines that carry no product:
- US sales tax — the item that carries the whole tax total of an invoice billed to a US address
- Ad-hoc line — the item used for manual lines and true-ups, which carry no product
The mapping is one per Alguna organization, and every legal entity shares it. Alguna picks the region from the invoice billing address. An invoice line whose product has no item stops the sync before Alguna writes anything, so the mapping needs to cover your whole catalog.
Step 4: Alguna turns on invoice sync
Once your mapping is in, Alguna enables invoice sync on the legal entities you mapped in step 2. From that point, issuing an invoice in Alguna sends it to NetSuite. Leave the Invoice Integration setting on the legal entity alone, because NetSuite receives an accounting copy and doesn’t issue the invoice to your buyer.Step 5: Run a test invoice
1
Pick a customer
Choose or create a customer on one of the mapped legal entities. Its company name must be 83 characters or shorter.
2
Check the customer in NetSuite
With the sync switch on, Alguna pushes the customer on create and on update. On the first invoice, Alguna also creates the customer if no link exists yet.If a NetSuite customer already has the exact same company name, Alguna adopts that record instead of duplicating it, and stamps its own external ID on it when the field is empty.
3
Issue an invoice
Issue an invoice on that customer. The invoice number must be 15 characters or shorter, and its currency must be active in NetSuite.
4
Check the invoice in NetSuite
Go to Transactions → Sales → Invoices. The record carries the Alguna invoice ID as its External ID, the Alguna invoice number as its Document number, and a status of Open.
5
Check for sync issues in Alguna
Look under Settings → Connections → Sync issues for anything the sync rejected. See Sync failures below.
What Alguna writes on an invoice
On the lines themselves:
- The rate is the Alguna unit price, and the price level is
Custom, so the item’s own list price doesn’t override it - The line description is the Alguna line description. A rolled-up invoice also appends the serviced customer name
- A US billing address adds one extra line carrying the whole tax total of the invoice, and only when that total is positive
- Outside the US, Alguna sends no tax, and NetSuite derives it from the customer’s country tax setup
- An applied amount. Once a payment or a credit note is applied, NetSuite resists edits, so Alguna leaves that invoice alone
- A void. A voided Alguna invoice is left in place in NetSuite and no longer updated
Sync failures
Problems detected before calling NetSuite (an unmapped product, a missing customer field) and errors returned by NetSuite (authentication, rate limits, validation) open a sync issue under Settings → Connections → Sync issues, with the reason and the affected invoice. Fix the mapping or the record and retry from there. See External sync for issue statuses and categories.
When a NetSuite invoice already holds your document number, Alguna adopts it rather than failing, but only when the customer, the currency, and the total all agree. Otherwise the write error surfaces as a sync issue.
Journal CSV export
Instead of posting invoices into NetSuite as they’re issued, Alguna can produce journal entry CSVs for your accountant to import. Use it when your finance team prefers to review a batch before it hits the ledger, or when NetSuite access is limited to an import step.Configure the export
On the connected NetSuite card, click the gear icon to open Configure, then go to the CSV exports tab and turn on Enable NetSuite CSV exports. Then set:
The account pickers read your live NetSuite chart of accounts and show income, other current liability, other current asset, accounts receivable, and bank accounts. All five settings are required, and the export refuses to run until each one holds a value.
Tax codes aren’t set here. Each line’s tax code comes from the tax mapping on its legal entity, matched on the line’s taxability reason, and the mapped NetSuite tax code needs a sale account on it.
Run the export
The export runs from Data exports on the invoices page as thenetsuite_journals dataset. Before running it you get a preview showing how many invoices and journal rows are pending, broken down by legal entity, along with whether each entity has a subsidiary mapped. Your current invoice list filters don’t apply: every invoice that hasn’t been exported yet is included.
Each run picks up issued, paid, and overdue invoices that this integration hasn’t exported before, so consecutive runs never re-export the same invoice. The preview tells you how many invoices were exported before and are left out, and how many of those have changed since their export. Tick Include invoices that have changed since their previous export to add the changed ones to this run; their earlier export records are retired in the same step, and the download lists the journals to reverse (see Re-exporting).
Files are split per legal entity and capped at 25,000 rows, always cutting at an invoice boundary so a journal entry is never split across two files. Each file carries its own batch ID, and every run is kept in the export history.
What’s in the file
Every journal file carries these columns:
Anything the export can’t turn into a balanced journal entry goes into a separate
issues file rather than silently dropping out, with the invoice, the line, the problem, and the action to take. Common entries are a legal entity with no subsidiary mapping, an invoice with no number or invoicing date, a currency that isn’t active in NetSuite, a line whose taxability reason matches no tax mapping rule, a mapped tax code with no sale account, and an exported invoice that changed or was voided afterwards. An issue is always something that kept an invoice out of the file.
When a run re-exports invoices that were exported before, the download also carries a reversals file: one row per journal line of the earlier export (invoice, line, External ID). Those are the journals to reverse in NetSuite before the new file is imported.
Export history
The Exports tab on the invoices page lists every journal export run: when it started, who requested it, whether it completed or failed, how many files, invoices, and issues it produced, and the earliest and latest issue dates of the invoices it contains. That interval describes only what the export holds; other invoices issued in the same period may not be part of it, and the file is the source of truth for what was exported. A failed run shows a plain reason on hover, such as NetSuite refusing the connection or being temporarily unavailable, so you know whether to reconnect, wait, or retry. Open a run to see its files and issues:- Files lists each file with its batch ID, legal entity, invoice and row counts, and its own issue-date interval. When a file was re-exported later, the row shows who did it, when, and which export carries those invoices now.
- Issues lists what was left out and why, with a link to each invoice.
Re-exporting
Use a re-export when an import failed or when invoices changed after they were exported. It builds a fresh file from the invoices as they are now, with your current export settings, and records a new run linked to the original. Three scopes are available:
Each dialog shows what it acts on (exports, files, invoices, and how many changed since their export) and offers Changed invoices only to limit the file to invoices whose content changed. The earlier export records are retired, so the invoices don’t come back in the next regular export.
Certificate renewal
The Alguna certificate is valid for two years, which is the NetSuite maximum. Alguna warns your organization administrators in the dashboard at 60, 30, and 14 days before expiry, and pauses the integration once the certificate expires. To renew, click Rotate certificate on the integration card. Alguna generates a new certificate, you create a new M2M mapping with it in NetSuite, and you paste the new Certificate ID back into Alguna. Revoke the old mapping only after the new one is verified.After a sandbox refresh
A sandbox refresh copies your production account over your sandbox account, so the sandbox holds fresh production data. Alguna neither triggers a refresh nor is told about one, and a refresh breaks the setup in two ways:- Everything that exists only in the sandbox is replaced by the production copy, so the integration role, the integration user, and the integration record are gone unless they also exist in production
- NetSuite never copies integration authorizations or M2M certificate mappings between accounts, and a refresh clears them, so the uploaded certificate is gone even when the records around it survive
- Recreate the integration role, user, and record, or as much of them as the refresh removed
- Reconnect the integration in Alguna with the new client ID, using Rotate certificate on the integration card to issue a fresh certificate to upload
- Check your subsidiary mapping and tell Alguna to re-check your product mapping, because both hold NetSuite internal IDs that the refresh may have changed
Related
- Invoicing configuration — when invoices are issued
- Credit notes — what becomes a credit memo
- Revenue recognition — revenue schedules alongside the ledger
- Migration checklist — connecting accounting during onboarding