> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chift.eu/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](#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.
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](https://reconcile-help.zoneandco.com/hc/en-us/articles/30258767667227-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](https://reconcile-help.zoneandco.com/hc/en-us/articles/30258736554779-Configuring-and-Understanding-Matching-Preferences-in-ZoneReconcile).
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](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/article_0107014921.html).
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](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_1498754928.html))
**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**. |
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.