NetSuite

How to connect your NetSuite account: what you need and how to connect.

🚨 Prerequisites

The following must be true in your NetSuite account before you start:

• You have an Administrator role, or a role with the SuiteApp Marketplace permission (needed to install a bundle).
• You have the Bundle ID provided by Chift: 703899 (or by your provider, for a branded bundle).
• Only if your software provider sends bank transactions to NetSuite: one more setup, described in Setup step 4. It depends on whether the ZoneReconcile SuiteApp is installed on your account.

Everything Chift needs (a script, a least-privilege role, the OAuth 2.0 integration record, and an attachments folder) is delivered by the bundle in one click. You never have to upload files, configure scripts manually, or copy a Client ID or Secret.

The whole setup is four steps: enable features → install the bundle → assign the role → authorize. If your provider sends bank transactions, add Setup step 4 before you authorize.

⚙️ Setup

You need to be logged in to your NetSuite account for the steps below.

☑ 1. Enable the right company features

Go to Setup > Company > Enable Features > SuiteCloud tab. Enable each of the following, save, and accept every Terms of Service prompt.

This must be done before installing the bundle: without Server SuiteScript enabled, the bundled script cannot install.

• SuiteScript → Client SuiteScript, Server SuiteScript

  

• Manage Authentication → OAuth 2.0

  

• SuiteTalk (Web Services) → REST Web Services

  

• Custom Records → Custom Records

  

If your account uses custom segments as analytical dimensions, also enable SuiteCloud > Custom Segments (you will grant the matching permission on the role later; the permission only appears once the feature is on).

☑ 2. Install the Chift bundle

Go to Customization > SuiteBundler > Search & Install Bundles, enter the Bundle ID 703899, review the list of objects, and click Install.

The script and its deployment, the Chift Integration role, the integration record, and the Chift Attachments folder are all installed in one click.

To remove the bundle later: Customization > SuiteBundler > List of Installed Bundles → select the bundle → Uninstall.

☑ 3. Assign the Chift Integration role (and re-login)

You can do this now or at connection time. Assigning the role up front is cleanest, but if it isn’t set here, the user can still select (or switch to) the right role at the NetSuite consent screen during connection (see Check the role at connection in the Connection section below).

The bundle installs the role definition, but does not assign it to a user. Assign it to the user who will connect to Chift.

Assign the role via Setup > Users/Roles > Manage Users > the user > Access subtab > add Chift Integration > Save.

✅ Recommended: use a dedicated integration user. Create or pick an employee whose only role is Chift Integration (no Administrator, no other role). This is what keeps the connection least-privilege at runtime.

If using your own role instead of the bundled ones: Add the Manage own OAuth 2.0 Client Credentials certificates permission (under Setup) to it. Without it, the connection still works, but it stays on the standard OAuth flow and needs re-authorizing roughly every 30 days. With this permission, it moves to certificate-based (machine-to-machine) authentication and never expires. You must also make sure that the Subsidiaries View/List permission is set on the used role.

You MUST log out and back in after assigning the role. NetSuite caches roles per session, so a newly assigned role only becomes selectable after the user logs out and logs back in. If you skip this, the role won’t appear at the consent screen in the next step.

☑ 4. Prepare bank transactions (only if your provider sends them)

Skip this step if your software provider doesn’t send bank transactions to NetSuite.

Once the setup is done and your first statements arrive, see Bank transactions in Good to know for where to find them and how to match them.

Bank statements reach NetSuite in one of two ways. You don’t choose it: it depends only on whether the ZoneReconcile SuiteApp from Zone & Co is installed on your account. To check, look for a Transactions > Bank Reconciliation menu: it only exists when ZoneReconcile is installed.

Bank transactions need the Chift Integration role (or your own role with the same access). Chift Integration (Read Only) cannot import bank statements.

ZoneReconcile is installed

Your bank statements are written to ZoneReconcile, and ZoneReconcile matches them to your open invoices and bills.

First, give the role you connect with Full access to ZoneReconcile’s two bank record types, Bank Statement and Bank Statement Transaction, and to Lists > Perform Search. Do it before you connect: without this access, the connection can’t see ZoneReconcile and fails with “Bank Statement Parsers is not installed.” If you grant it later, test the connection again.

Then, in ZoneReconcile, for each bank account that will receive statements:

1. Create its Bank Account Configuration, under Setup > Bank Reconciliation Setup > Bank Account Configurations (Setup > ZoneReconcile Setup > Bank Account Configuration in older versions). Fill in the catch-all GL account, the counterparty name field, and the default payables and receivables accounts. ZoneReconcile only matches statements of a bank account that has one.
2. Set its Matching Preferences, for debits and for credits. For example, Match Open Credits on Exact match of amount to match customer payments by amount.
3. Set its Processing Preferences.

Currencies: a bank account in a foreign currency only pays invoices in that same currency. A bank account in your base currency can pay invoices in any currency. To pay a base-currency invoice from a foreign-currency bank account, NetSuite needs a transit account: see Zone & Co’s Foreign Currencies.

For document number matching, ZoneReconcile only considers references of at least 4 characters that contain a digit, unless Allow non-numeric matches is enabled. See Matching Preferences.

ZoneReconcile is not installed

Your bank statements go through NetSuite’s own bank data import, and you match them in Match Bank Data. Set it up once:

Do steps a to g before you connect.

a. Check the integration bundle version. Bank statements without ZoneReconcile need version 1.4 or later of the bundle from Setup step 2. In Customization > SuiteBundler > List of Installed Bundles, check its version. If it is older, open it and click Update: it never updates by itself. Version 1.4 adds the Chift Bank Statement Import plug-in and the Chift Bank Statements File Cabinet folder. Keep exactly one folder with that name, and don’t rename it.

b. Install the Bank Statement Parsers SuiteApp. Go to Customization > SuiteBundler > Search & Install Bundles, click Advanced, search for Bundle ID 293699 (Bank Statement Parsers, by Oracle NetSuite, free), and click Install. It needs the same features as Setup step 1. The bundle shows Pending… for a few minutes after the install.

c. Enable the two plug-ins. Go to Customization > Plug-ins > Manage Plug-ins, check Chift Bank Statement Import and CSV Plugin Implementation, and click Save. If one stays unchecked, nothing is imported and nothing shows in Banking Import History.

d. Create a Financial Institution. Go to Setup > Accounting > Financial Institution > New. Fill in Financial Institution, for example the name of your bank, and click Save.

e. Add its format profile. Open the saved Financial Institution in View mode: in Edit mode, Add does nothing. In the Format Profile: Configuration subtab, click Add and fill in:

Field	Value
Profile Name	Any name, for example Bank statements format profile
Profile Type	Bank Reconciliation
Connectivity Method	Chift Bank Statement Import
Transaction Parser	CSV Plugin Implementation

Click Save. Keep only one active format profile on this Financial Institution.

If Chift Bank Statement Import isn’t in the list, check steps a and c. If CSV Plugin Implementation isn’t in the list, check steps b and c.

f. Leave the parser settings as they are. In the profile’s Parser Configuration subtab, keep the defaults. A custom date format may only use M, D and Y, for example DD/MM/YYYY. If you change the parser settings later, statements sent before the change and not imported yet may break or be skipped: delete those files from the Chift Bank Statements folder and ask your provider to send them again.

g. Prepare each bank account. For each bank or credit card account that will receive statements, open it in Lists > Accounting > Accounts, click Edit, enable it for Match Bank Data and Reconcile Account Statement, and click Save. It also needs:

• an account number, with no underscore (_) in it, used by no other active account
• a currency whose ISO Code is the three-letter ISO 4217 code, for example EUR or GBP

You don’t need to fill in Account Linking: each bank account is added there on its first statement.

h. After your first statement: choose how often NetSuite imports. Once a bank account is linked, NetSuite imports new statements once a day by default. You can change this in the profile’s Import Schedule subtab: a Unit of Time (hour or day), a Frequency, an Import Date, an Import Time and a Time Zone. Fill in all of them, or leave all of them empty. See Oracle’s Setting Up a Bank Import Schedule.

You will choose this Financial Institution when you connect, in the Financial institution field.

---

⚡️ Connection

In Chift, start the NetSuite connection and follow the steps.

Step 1: Choose a name for your connection.

Step 2: Fill in your NetSuite Account ID.

Your Account ID is at the beginning of your NetSuite URL, e.g. https://1234567.app.netsuite.com → Account ID is 1234567. For sandbox accounts, replace the dash in the URL (sb-) with an underscore (sb_), e.g. sb-12345 is entered as sb_12345. (NetSuite doc)

Step 3: Click Authorize. When prompted, enter your credentials (associated with the app) to connect your NetSuite account.

Connect with the role you want Chift to use, not as Administrator. The connection runs with whatever role the user authorizes with. If an Administrator connects, it runs with full administrator access. Log in as the user carrying the scoped role you assigned in Setup step 3 (read + write, read-only, or your own role).

Check the role at connection. At the consent screen, NetSuite shows the role the connection will use. If the right role wasn’t assigned during preparation, or the wrong one is preselected, check it here and switch to the correct role before confirming.

Click Continue and that’s it: no Client ID, Client Secret, or RESTlet URL to enter. Standard accounting data and the script-backed features (attachments; bank transactions where applicable) all run over the same OAuth 2.0 connection.

Financial institution (only if your provider sends bank transactions). After you authorize, the connection window may ask for a Financial institution:

• ZoneReconcile is not installed: choose the Financial Institution you created in Setup step 4. Only the ones with a format profile set up as described there are listed.
• ZoneReconcile is installed: the list is empty. Leave the field as it is.

---

ℹ Good to know

Roles & permissions.

The bundle ships two roles: Chift Integration (read + write) and Chift Integration (Read Only). You can also connect with your own NetSuite role scoped to your needs; in that case reach out to your software provider from which you are initiating this connection, to know the minimal set of permissions required for the scope of your integration with Netsuite.

🚨 Staying on machine-to-machine authentication (no monthly reconnects).

Whichever role you connect with (bundled or your own), it needs the Manage own OAuth 2.0 Client Credentials certificates permission (under Setup on the role’s permission list) for the connection to move to certificate-based authentication and stop requiring reconnection every ~30 days. The bundled Chift Integration roles already carry it. If you’re using your own role, add it manually:

You’ll also need Client Credentials (Machine To Machine) Grant ticked on the NetSuite integration record itself (same screen as the REST Web Services and RESTlets scope checkboxes). This only applies if you’re using your own integration record rather than the Chift bundle.

Without both, the connection keeps working normally, it just stays on the standard flow and needs re-authorizing about once a month.

OneWorld (multi-subsidiary) accounts.

The Chift Integration role ships with Subsidiary Restrictions = All so the connector can see every subsidiary. If this is changed to User Subsidiary, or if the user’s Include Sub-Subsidiaries preference is off (Home > Set Preferences > Restrict View), child subsidiaries won’t appear in Chift. Re-login after changing either.

Attachments folder.

The bundle ships a Chift Attachments File Cabinet folder as the default target for stored attachments. You can point Chift at another folder in the post-connection settings. Do not rename the bundled folder: Chift matches it by the exact name Chift Attachments.

Bank transactions.

Bank transactions only need the setup of Setup step 4. Attachments and all standard accounting features do not depend on it. Your software provider sends the bank statement lines; you match them in NetSuite or in ZoneReconcile.

If ZoneReconcile is installed, your statements appear in ZoneReconcile, under Transactions > Bank Reconciliation. They are not matched on their own. For each statement:

1. Open the statement and click Run Match. ZoneReconcile finds the matching invoices and bills with your Matching Preferences.
2. Click Edit, then Save. This is what creates the payments: Run Match alone posts nothing.

If ZoneReconcile is not installed, your statements appear in Transactions > Bank > Bank Matching and Reconciliation > Match Bank Data:

1. Choose the bank account in Account. A statement your provider sends is in NetSuite, but its lines only show up after the next import. The first one shows up by itself within minutes. If it doesn’t, click Update Imported Bank Data. Later ones come with the import schedule (Setup step 4, h), or sooner with Update Imported Bank Data. NetSuite allows one import every 60 minutes per Financial Institution, for all its bank accounts together.

2. In the To Be Matched tab, the statement lines are under Imported Bank Data, and your NetSuite transactions under Account Transactions. Select a line on each side and click Match. When no transaction fits, select only the statement line and use Add Journal Entry, Add Charge or Add Deposit. Use Exclude for a line you don’t want to match.

   

3. In the Review tab, check the matched lines and click Submit Selected or Submit All. The matches are only recorded when you submit. Until then, Undo Selected sends a line back to To Be Matched.

   

A bank line is matched to a payment or another transaction, not directly to an open invoice or bill.

---

❓ Troubleshooting

Symptom	Cause	Fix
Connection keeps asking for reconnection every ~30 days even though everything else is set up correctly	Custom role is missing Manage own OAuth 2.0 Client Credentials certificates, or the integration record doesn’t have Client Credentials (Machine To Machine) Grant ticked	Add the permission to the role and/or tick the grant on the integration record, then run Test Connection
INSUFFICIENT_PERMISSION / “You do not have privileges to view this page” on attachment or bank calls	You connected as Administrator instead of the Chift Integration user, or the token’s role isn’t in the script deployment’s audience	Reconnect as the dedicated integration user (Connection step 3).
The Chift Integration role isn’t selectable on the consent screen	Role assigned but the session wasn’t refreshed	Log out and back in as the integration user (Setup step 3), then retry.
Subsidiary list shows only the parent (OneWorld)	Role’s Subsidiary Restrictions = User Subsidiary, or Include Sub-Subsidiaries is off	Set Subsidiary Restrictions = All on the role, enable Include Sub-Subsidiaries, then re-login.
The Chift Attachments folder doesn’t appear in the folder dropdown	Folder was renamed	Keep the exact name Chift Attachments.
Bundle won’t install (“script cannot be deployed”)	Server SuiteScript / Custom Records feature not enabled	Complete Setup step 1 before installing.
A specific endpoint returns a 403 at runtime	The role is missing that transaction/list permission	Grant the missing permission on the Chift Integration role.
”Bank Statement Parsers is not installed.”	The Bank Statement Parsers SuiteApp isn’t installed, and ZoneReconcile isn’t installed or your role can’t read its bank records	Install bundle 293699 (Setup step 4, b). If ZoneReconcile is installed, give your role access to its bank records (Setup step 4, ZoneReconcile tab), then test the connection again.
”The bank statements folder is not set up.”	The Chift Bank Statements folder installed by the bundle was renamed, deleted or duplicated	Keep exactly one active folder with that exact name (Setup step 4, a).
”No single bank reconciliation format profile is set up for the import.”	The Financial Institution has no format profile with Chift Bank Statement Import and CSV Plugin Implementation, or has several active ones	Keep exactly one active format profile set up as in Setup step 4, e.
”No financial institution is selected for the bank statement import.”	The Financial institution field was left empty	Choose your Financial Institution in the connection settings (Connection section).
The Financial institution list is empty, and ZoneReconcile isn’t installed	No active format profile uses both Chift Bank Statement Import and CSV Plugin Implementation	Set up the format profile (Setup step 4, e), then open the connection settings again.
”Script extension version not valid.”	The integration bundle installed on your account is too old for bank statements	Update the bundle 703899 (Setup step 4, a).
”The bank account … is not enabled for bank data matching.”	The bank account isn’t enabled for Match Bank Data	Enable it for Match Bank Data and Reconcile Account Statement (Setup step 4, g).
”NetSuite did not store the Account Linking row for bank account …”	The bank account could not be added to the format profile	In the format profile’s Account Linking subtab, add the bank account yourself.
”The bank account number is missing or contains an underscore.”	The NetSuite bank account has no account number, or it contains _	Give the bank account a number without _ (Setup step 4, g).
”The currency symbol … in NetSuite is not the ISO 4217 code …”	The ISO Code of the bank account’s currency is not the standard three-letter code	In Lists > Accounting > Currencies, open the currency and set ISO Code to the ISO 4217 code, for example EUR.
”Bank account … is linked to another general ledger account … in NetSuite.”	In the format profile’s Account Linking, this account number is already linked to another account	Fix or remove that row in Account Linking.
”The date format … of the bank statement parser configuration is not supported.”	The format profile’s parser uses a date format without month, day and year	In the format profile’s Parser Configuration, use a date format with only M, D and Y (Setup step 4, f).
Bank statements don’t appear in Match Bank Data	They are waiting for the next import	Click Update Imported Bank Data, at most once every 60 minutes.
Still nothing in Match Bank Data or in Banking Import History after Update Imported Bank Data	A plug-in isn’t enabled	Check Chift Bank Statement Import and CSV Plugin Implementation in Manage Plug-ins (Setup step 4, c).
Update Imported Bank Data: “Your account is not configured with a bank connection”	No statement was sent for this bank account yet, so it isn’t linked to the format profile	Wait for your provider to send a first statement, then retry.
”You can only import bank data for an account every 60 minutes.”	An import ran for this Financial Institution less than an hour ago	Retry after an hour, or wait for the scheduled import.
”Record ‘formatprofile’ was not found”, or “You need the ‘SuiteScript’ permission”	You connect with your own role, and it lacks Setup > Financial Institution Records or Setup > SuiteScript	Grant Financial Institution Records at Full and SuiteScript at View, plus Lists > Documents and Files at Create.