Before configuring the NetSuite and Alvys TMS integration, your NetSuite environment must be properly prepared. Most integration failures result from misconfigured features, roles, users, or improper subsidiary access. NetSuite supports two secure authentication mechanisms: OAuth 2.0 and Token-Based Authentication (TBA).
Alvys connects to NetSuite using Token-Based Authentication (TBA) through SuiteTalk REST Web Services. This secure authentication method allows encrypted API communication without storing user credentials.
This guide outlines the required configurations to ensure your NetSuite account is properly set up for the Alvys integration.
1️⃣ NetSuite Account
An active NetSuite account with Administrator-level access (or a role with equivalent permissions) is required. This account is typically associated with the employee responsible for managing system settings and configurations. In NetSuite, administrator accounts are linked to an employee record, representing an individual authorized to log in and make system changes.
Purpose of Administrator Access
Administrator access is required only during setup to enable critical NetSuite features such as Web Services and Token-Based Authentication, create or modify user roles, establish an integration record, and generate secure authentication tokens.
💡 Do not use your personal Administrator login for the live integration.
Instead, during setup you will create a dedicated integration role specifically for Alvys. This ensures:
Improved security
Clear separation between user activity and system activity
Easier troubleshooting and management
Your Administrator account is only used to prepare the system, not to run the integration long term.
2️⃣ Enable Required NetSuite Features to communicate with Alvys
NetSuite must have the appropriate web services and authentication features enabled before Alvys can connect.
Required Features
REST Web Services – Allows NetSuite to share data with Alvys
SOAP Web Services - This is also recommended to ensure compatibility with all supported record types.
Token-Based Authentication (TBA) – Allows secure system access without using a password
Suite Script - While Alvys does not deploy custom scripts in your account, Suite Script is required for NetSuite’s REST and SOAP Web Services to function properly, including internal searches and record queries executed by the integration.
💡 OAuth 2.0 is not required for this integration. Alvys authenticates exclusively using Token-Based Authentication (TBA) through SuiteTalk Web Services.
Steps:
Log in to NetSuite using your administrator account
Navigate to Setup, then Company, and select Enable Features
Open the SuiteCloud tab
In the SuiteTalk (Web Services) section, enable SOAP Web Services and REST Web Services to allow secure data exchange with Alvys.
In the Manage Authentication section, enable Token-Based Authentication (TBA) to allow Alvys to connect securely without storing login credentials
In the Suite Cloud tab, locate the SuiteScript section and enable SuiteScript.
Click Save to confirm the changes.
⚠️ Missing any of these features may cause authentication failures or prevent transaction data from being exported correctly.
3️⃣ Integration Roles and User Setup
To connect Alvys to NetSuite securely, a dedicated integration role and a dedicated integration user are required. This separates automated API access from human administrator accounts and restricts permissions to only what is necessary for the integration.
Create a Dedicated Integration Role
The integration role defines the permissions Alvys needs to access NetSuite records and perform API actions. If a suitable role does not already exist, create one:
Navigate to Setup, then Users/Roles, and select Manage Roles, then click New
Enter a descriptive name such as “Alvys Integration Role”.
Assign Subsidiary Access: If your account uses NetSuite OneWorld, assign access to all subsidiaries used in Alvys. If transactions span multiple subsidiaries, enable Cross-Subsidiary Record Viewing.
All Subsidiaries (recommended) or select only the subsidiaries used in Alvys
Allow Cross-Subsidiary Record Viewing
Optional: Restrict the role to Web Services Only
Restricting the role to Web Services prevents users from logging in through the NetSuite interface. This enhances security by ensuring the role is used exclusively for API access and cannot be exploited for human login.
Click Save
Assign Permissions
The integration role must include permissions across Setup, Transaction, and List categories. Missing permissions will cause transaction exports to fail even if authentication is successful.
Setup Permissions
Setup permissions control access to system-level features in NetSuite, such as APIs, authentication, and administrative functions. For Alvys, the integration role requires:
REST Web Services (Full Access)
SOAP Web Services (Full Access)
Login Using Access Tokens (Full Access)
SuiteScript (Full Access)
Accounting Lists (Full Access)
Custom Fields (Full Access)
Custom Item Fields (Full Access)
Custom Body Fields (Full Access)
Custom Column Fields (Full Access)
Custom Transaction Fields (Full Access)
Custom Entity Fields (Full Access)
Custom Record Types (Full Access)
Custom Segments (Full Access)
Custom Lists (Full Access)
Other Lists (Full Access)
Deleted Records (Full Access)
Manage Accounting Periods (View Access)
Financial Institution Records (Full Access)
Transaction Permissions
Transaction permissions determine which records Alvys can create, modify, or delete in NetSuite. These permissions should be assigned with Full access for each relevant record to ensure the integration functions properly. Examples of required transaction permissions include:
Invoice
Bills
Customer Payments
Pay Bills
Vendor Credits
Credit Memos
Customer Deposit
Make Journal Entry
It is essential that the role has access to all required record types. If any permissions are missing, exports may fail even if authentication is successful.
List Permissions
The integration role requires access to specific lists in NetSuite to ensure that transactions and records are created, updated, and categorized correctly. Assign the following permissions:
Accounts – Full access
Address List in Search – Full access
Contacts – Full access
Customers – Full access
Vendors – Full access
Employees – View access
Employee Record – View access
Expense Categories – Full access
Payment Methods – Full access
Currency – Full access
Items – Full access
Perform Search – Full access
Custom Record Entries – Full access
Classes – Full access (optional, used for categorizing transactions)
Departments – Full access (optional, used for categorizing transactions)
Locations – Full access (optional, used for categorizing transactions)
Subsidiaries – View access (or Full access if the integration requires access across multiple subsidiaries
Contact-Subsidiary relationship – View access
Companies – Full access
Tax Records – View access
Documents and Files - Full access
Create a Dedicated Integration User
The integration user is a separate NetSuite employee or service account that Alvys uses to authenticate API calls. Using a dedicated user ensures secure access and keeps integration activities separate from human users.
Navigate to Lists, then Employees, and select New (or choose an existing service or system employee). Example: “[email protected]”
Assign the Alvys Integration Role created in the prior step:
Under Roles, select the “Alvys Integration Role”.
Click Save to create the user. You now have a dedicated integration user that Alvys will use to authenticate API calls.
💡 Admin account: used only to enable features, create roles, create integration records, and generate tokens.
Dedicated Integration User (employee record/service account) → used by Alvys to authenticate via REST/TBA.
4️⃣ Generate Integration Credentials for Token-Based Authentication
Alvys requires five (5) credentials to connect to NetSuite securely:
Account ID/ Realm ID
Consumer Key
Consumer Secret
Token ID
Token Secret
These credentials are generated using the Integration Record, Integration User, and Integration Role created in the previous steps.
Locate Your NetSuite Account / Realm ID
The Account ID, also known as the Realm ID, appears in the NetSuite URL. In production environments, it typically appears as a numeric value before “app.netsuite.com.” Sandbox accounts include a suffix, such as “_SB1” or “-sb1.” The Account ID must match the exact environment where the integration is being configured.
For example: “https://123456.app.netsuite.com”: Account ID is 123456
Create the Integration Record
Navigate to Setup, then Integrations, and select Manage Integrations, then click New.
Enter a descriptive name, for example, “Alvys TMS Integration”.
Enable Token-Based Authentication.
Click Save.
Copy the Consumer Key and Consumer Secret.
⚠️ These are displayed only once. Store them securely. If lost, they must be regenerated.
Generate Access Tokens
Go to Setup, then Users/Roles, and select Access Tokens, then click New.
Select the following:
Application Name – Choose “Alvys TMS Integration”, the integration record you just created
User – Select the dedicated integration user
Role – Select the dedicated integration role assigned to that user
Click Save.
Copy the Token ID and Token Secret.
⚠️ These are displayed only once. Store them securely. If lost, they must be regenerated.
5️⃣ Ensure a Complete Chart of Accounts Exists in NetSuite
The Chart of Accounts contains all financial accounts used for posting transactions in NetSuite.
Before exporting transactions from Alvys, confirm that all required income, expense, asset, liability, and clearing accounts exist and are assigned to the correct subsidiaries (if using OneWorld).
Use this official NetSuite documentation for additional instructions: Creating Accounts
Basic Steps to Create a New Account
Log in to NetSuite with a role that has accounting permissions.
Go to Lists, select Accounting, then select Accounts, and click New.
Select the Type of account, such as Income, Expense etc.
Enter the Account Name.
If your organization uses account numbers, enter a number. Account numbering must be enabled under Setup, Accounting, Accounting Preferences.
Optionally assign the account to a parent account or a subsidiary for OneWorld users.
Click Save.
⚠️ Make sure all required accounts are created before pushing transactions from the Alvys TMS.
6️⃣ Subsidiaries Must be Set up
If the account uses NetSuite OneWorld, subsidiaries must be created and fully configured before enabling the integration. Each subsidiary must have a base currency, appropriate tax configuration, and access to the correct chart of accounts.
After subsidiaries are established, confirm that the Alvys Integration Role has access to all relevant subsidiaries. Transactions cannot post to subsidiaries that are not assigned to the integration role.
Proper subsidiary configuration is essential to avoid posting and validation errors. Use this official NetSuite documentation for additional instructions: Creating Subsidiary Records
Steps to Create a Subsidiary
Navigate to Setup > Company > Subsidiaries.
Click New to create a subsidiary.
Enter the Name of the subsidiary.
Assign a Base Currency for the subsidiary.
Select the Parent Subsidiary, if applicable, to maintain a hierarchical structure.
Assign a Chart of Accounts that will be used for transactions in this subsidiary.
Complete any required tax settings and other relevant configuration fields.
Click Save to create the subsidiary.
Assign Role Access
After creating the subsidiary, ensure the Alvys Integration Role has access to it. Without proper access, transactions for that subsidiary will fail during exports.
Assign Subsidiary Access to a Role
Navigate to the Role:
Go to Setup → Users/Roles → Manage Roles and select the integration role (e.g., Alvys Integration Role).
Edit the Role:
Click Edit next to the role name.
Locate Subsidiary Access:
In the role record, find the Subsidiary Restrictions or Subsidiary Access section.
Set Access Level:
All – allows the role to access all subsidiaries in the account (recommended)
Selected – allows access to only specific subsidiaries; if you choose this, check all subsidiaries that Alvys will need.
Enable Cross-Subsidiary Record Viewing
Save the role.
Common Gotchas
Required features not enabled
Token created under the wrong role
Missing transaction or list permissions
Subsidiary not assigned to the role
Role permissions modified after token generation
Required accounts not created in NetSuite
⚠️ Any of these will cause authentication or export failures.
FAQs
Q: What level of NetSuite access is required to set up the Alvys integration?
A: An Administrator-level account (or a role with equivalent permissions) is required only during setup to enable features, create roles, and generate tokens. The integration itself uses a dedicated integration user.
Q: Can I use my personal Administrator login for the live integration?
A: No. A dedicated integration user and role should be created to separate API access from human accounts, improving security and making troubleshooting easier.
Q: Which NetSuite features must be enabled for Alvys to connect?
A: REST Web Services, SOAP Web Services, Token-Based Authentication (TBA), and SuiteScript must all be enabled. OAuth 2.0 is not required.
Q: What happens if required NetSuite features are not enabled?
A: Missing features can cause authentication failures or prevent transaction data from being exported correctly.
Q: What permissions are required for the integration role?
A: The integration role requires permissions across Setup, Transaction, and List categories, including full access to Web Services, SuiteScript, accounting lists, customers, vendors, items, and all relevant transactions.
Q: Should the integration role be restricted to Web Services only?
A: Yes, restricting the role to Web Services enhances security by preventing login through the NetSuite interface.
Q: How do I create the integration user?
A: Create a new employee record (or use a service account) and assign the dedicated integration role. This user will authenticate API calls from Alvys.
Q: What credentials does Alvys require to connect to NetSuite?
A: Alvys requires the Account ID (Realm ID), Consumer Key, Consumer Secret, Token ID, and Token Secret. These are generated using the integration record, integration role, and integration user.
Q: Where can I find my NetSuite Account ID / Realm ID?
A: The Account ID is in the NetSuite URL, before “app.netsuite.com.” Sandbox accounts include a suffix, e.g., “_SB1.”
Q: Can tokens be regenerated if lost?
A: Yes, but you must regenerate them in NetSuite. Consumer Key, Consumer Secret, Token ID, and Token Secret are shown only once.
Q: Are all Chart of Accounts and subsidiaries required before exporting transactions?
A: Yes. Ensure all required accounts exist and subsidiaries are fully configured. The integration role must have access to all relevant subsidiaries.
Q: What are common causes of integration failures?
A: Integration failures can result from missing features, tokens created under the wrong role, missing permissions, unassigned subsidiaries, modified role permissions after token generation, or missing accounts.
Q: Is SuiteScript required for the integration?
A: Yes, SuiteScript must be enabled to allow NetSuite’s REST and SOAP Web Services to function properly, even though Alvys does not deploy custom scripts.
Q: Can I limit the integration role to selected subsidiaries?
A: Yes, but make sure all subsidiaries used in Alvys have access; otherwise, transaction exports to those subsidiaries will fail.
Q: Does the integration support OAuth 2.0 authentication?
A: No. Alvys uses only Token-Based Authentication (TBA) via SuiteTalk REST Web Services.
Next Steps
⏭️ Continue with NetSuite: Authentication and Settings Configuration in Alvys to establish a secure connection between Alvys and NetSuite and configure the necessary settings. This step ensures that Alvys can authenticate correctly and communicate with NetSuite using the credentials and configuration you prepared.
Return to Collection
📁 Need to see the full list of articles? Return to the NetSuite Integration Collection.