Skip to main content
To setup the Orb NetSuite integration, you’ll need to:
  1. Setup and configure NetSuite. This ensures the integration is compatible with your NetSuite configuration.
  2. Install the Orb NetSuite Integration bundle. This deploys the custom records and scripts to enable the integration behaviors in NetSuite.
  3. Generate your NetSuite connection credentials. You’ll use these inputs to authenticate the Orb and NetSuite connection.
  4. Create an integration user. This is the login the integration to access NetSuite.
  5. Configure the integration in Orb. This is where you define what and how Orb syncs to NetSuite.
  6. (Optional) Manually configure custom records required for credit drawdown. If you use prepaid credits in Orb, additional setup is required to enable syncing credits and recognizing item-specific revenue in NetSuite.

​
Step 1: Setup and configure NetSuite

You will need to do this with a user with Administrator access to your NetSuite account.

​
Align timezones

Optional: this setting is strongly recommended, but not functionally required for the integration.
Orb and NetSuite should be configured to the same timezone to ensure transaction timestamps align correctly during sync. Mismatches can cause invoices to post to the wrong accounting period, and make debugging more difficult.  Finding your timezone settings:
  • NetSuite: Setup > Company > Company Information
  • Orb: Settings > General > Account time zone (contact Orb Support to change this)
If new to Orb, set your timezone to be the same as NetSuite’s. Note that timezone changes are not retroactive — existing transaction timestamps will not be updated. If you don’t have an existing preference, we recommend UTC (UTC+00:00) for both systems.

​
Enable auto-generated numbers for customer creation

Optional: this setting is strongly recommended, but not functionally required for the integration.
Orb relies on NetSuite generating a unique numeric ID for each customer record to ensure syncs are idempotent. Auto-Generated Numbers must be enabled for the Customer record type in NetSuite to generate a unique numeric ID. Otherwise, NetSuite will default to the customer name as the customer ID, which can cause the sync to fail. Setup > Company > Auto-Generated Numbers. Check enable for Customer entity type.
Note: this is a NetSuite-only sequential record identifier, and does NOT modify any other customer identifiers you may already reference in NetSuite. It is also separate from the Orb customer ID, and is usually distinct from the external customer ID.

​
Enable features

Ensure the following features are enabled or selected. Setup > Company > Enable Features.
SubtabFeatureWhat it doesRequired?
Company
  • Multiple Currencies (if billing in more than one currency) checked
  • File cabinet checked
  • Enables billing and transaction processing in more than one currency. Required if Orb is invoicing customers in multiple currencies.
  • Provides access to NetSuite’s internal file storage.
  • Yes, if If billing in multiple currencies
  • Yes
Accounting
  • Accounting checked
  • Advanced Revenue Management (ARM) – Essentials checked
  • Rule-Based Recognition Treatment checked
  • Enables core accounting features including invoices, credit memos, and GL posting.
  • Enables revenue arrangements, recognition schedules, and deferred revenue management for Orb to handle revenue correctly.
  • Applies the correct revenue recognition rule to each transaction line based on configurable criteria. Required for multi-element arrangements with mixed recognition treatments (like usage).
  • Yes
  • Yes
  • Yes
TaxIf calculating tax in Orb
  • Advanced taxes checked
  • SuiteTax unchecked
  • Unlocks per-line tax calculation, multi-jurisdiction tax codes, and the tax infrastructure required for Orb’s tax override to function correctly.
  • NetSuite’s newer tax engine — incompatible with Orb’s tax override implementation, and other existing tax modules.
  • Yes, if calculating tax in Orb
  • Yes, if calculating tax in Orb
Transactions
  • Sales Orders checked
  • Return Authorizations checked
  • Advanced Shipping checked
  • Enables the sales order transaction type, which Orb uses to handle initial sale / invoice generation.
  • Enables the return authorization (RMA) transaction type, which Orb uses to handle invoice reversals and credit memo generation.
  • Enables unchecking fulfillment workflows on Items.
  • Yes, if using sales orders
  • Yes, if using RMAs
  • Yes
SuiteCloud
  • Custom records checked
  • OAuth 2.0 checked
  • Service SuiteScript checked
  • REST Web Services checked
  • Enables creation and use of custom data structures in NetSuite.
  • Enables token-based authentication for external systems connecting to NetSuite.
  • Enables server-side scripts to run within NetSuite.
  • Enables NetSuite’s native REST API endpoints for external integrations.
  • Yes
  • Yes
  • Yes
  • Yes

​
Accounting preferences

Ensure the following accounting preferences are selected. Setup > Accounting > Accounting Preferences.
SubtabFeatureWhat it doesRequired?
General
  • Require Invoice Approval When Revenue Plans Are Created On Billing unchecked
  • If checked, this approval step blocks Orb from completing the sync.
  • Yes
Order Management
  • Default Sales Order Status = Pending Fulfillment*
  • Default Return Authorization Status = Pending Receipt*
  • Invoice in Advance of Fulfillment checked
  • Bill in Advance of Receipt checked

* If your NetSuite admin has configured any approval workflows, keep in mind that transactions will not be created until after the record is approved for billing.
  • Bypasses approval workflows that could block Orb from completing the sync.
  • Bypasses approval workflows that could block Orb from completing the sync.
  • Ensures invoice creation is not blocked on fulfillment.
  • Ensures returns are not blocked on receipt.
  • No
  • No
  • Yes
  • Yes

​
Revenue Field Mapping

Orb syncs line-level service period start and end dates to custom transaction line fields installed via the bundle. This ensures the values are reliably preserved during transaction creation and transformation in NetSuite. To enable proper revenue recognition set up by your administrator, map these custom fields to NetSuite’s native revenue recognition start and end date fields. Setup > Accounting > Revenue Field Mapping > New. Ensure revenue recognition field mappings have been created to reference the custom service start and end dates synced from Orb.
Source fieldTarget field
Orb Rev Rec Start DateStart Date
Orb Rev Rec Start DateForecast Start Date
Orb Rev Rec End DateEnd Date
Orb Rev Rec End DateForecast End Date

​
Item configuration

Orb supports syncing Non-Inventory and Service type item records. For each Item in NetSuite that corresponds to an item synced from Orb, ensure the following fields are set. Lists > Accounting > Items.
SubtabFieldWhat it doesRequired?
Primary information
  • Includes children (unchecked)
  • Best practice to ensure specific subsidiary visibility.
  • No
AccountingIf sales tax is calculated in Orb.
  • Tax schedule = Taxable
  • Tells NetSuite to apply tax to this line item, which allows Orb to write the pre-calculated tax amount using the tax override code.
  • Yes, if calculating tax in Orb
PreferencesEnsure Advanced Shipping feature is enabled*
  • Can be Fulfilled/Received (unchecked)

*Non-inventory items only
  • Removes the fulfillment requirement from this line item, which can block record creation.
  • No, but strongly recommended
To bulk update item configurations in NetSuite, use the built-in CSV import tool at Setup > Import/Export > Import CSV Records. This allows you to update fields across multiple item records simultaneously without editing them one by one.

​
Tax configuration (if applicable)

If you bill and collect tax on invoices in Orb, configure NetSuite to receive tax amounts for accurate reporting in NetSuite. Our approach If you use Orb to calculate tax (for example via Avalara, Stripe Tax, or another provider) and want those amounts to be reflected exactly in NetSuite, you’ll need a dedicated “Orb Tax Override” code in NetSuite. Orb uses this code together with NetSuite’s taxamountoverride behavior so that NetSuite respects the tax amounts Orb sends, instead of recalculating tax based on its own rates. For sales order flows, we intentionally suppress estimated tax on the sales order and ensure the final invoice carries the correct tax/GL impact with no revenue impact or duplication.  1. Enable per-line taxes on transactions The “per-line taxes on transactions” setting tells NetSuite to calculate and display tax at each transaction line instead of only at the header/body level. For Orb, this is required so our tax override can populate line-level tax behavior correctly rather than collapsing tax to the transaction total. To enable it, Setup > Accounting > Tax Preferences, open the relevant country tab (for example, United States), and check the “per-line taxes on transactions” option. If you don’t see this field, ensure Advanced Taxes is enabled. 2. Create an Orb tax override code
  1. Create a new tax code for Orb under Setup > Accounting > Taxes > Tax Codes > New.
    1. Name it “Orb Tax Override”.
    2. Set the tax rate to 0%.
    3. Choose the appropriate tax type and tax agency for your environment.
    4. Ensure it is in the correct subsidiary.
  2. Save.

​
Step 2: Install the Orb NetSuite Integration bundle

  1. Navigate to Customization > SuiteBundler > Search & Install Bundles.
  2. Search Orb NetSuite Integration Bundle. ID: 597717. (Ask Orb to approve bundle access before installation.)
  3. Select the bundle from the results and click Install.
  4. Wait for the installation to complete. This may take a few minutes.
The bundle will install SuiteScripts and custom objects (fields, records, roles, etc) into your NetSuite account.

​
What’s in the bundle

  • 14 transaction line custom fields + 6 body fields + 1 entity field
  • 1 custom error record type
  • Orb Integration Role (includes ~50 required permissions for minimum integration functionality)
  • RESTlet + bundle installation script
These components are locked – you cannot edit/view field definitions.
Custom FieldsScript IDPurpose
Entity fields
Orb customer IDcustentity_orb_external_idRepresents the Orb external ID for the customer that triggered the creation of this NetSuite customer.
Transaction body fields
Orb invoice numbercustbody_orb_invoice_numberRepresents the Orb invoice number that triggered the creation of this NetSuite record.
Orb credit note numbercustbody_orb_creditnote_numberRepresents the Orb credit note number that triggered the creation of this NetSuite record.
Orb credit block IDcustbody_orb_credit_block_idRepresents the credit block ID that triggered the creation of this NetSuite record. Only applicable for recognizing prepaid credit drawdown.
Orb originating invoicecustbody_orb_originating_invRepresents the purchase invoice tied to the creation of this NetSuite record. Only applicable for recognizing prepaid credit drawdown.
Orb prepaid credit typecustbody_orb_prepaid_credit_typeRepresents whether this record corresponds to ab Allocation or Manual credit block in Orb. Only applicable for recognizing prepaid credit drawdown.
Orb subscription IDcustbody_orb_subscription_idRepresents the Orb subscription that triggered the creation of this NetSuite record. Only applicable for Subscription-driven sales order mapping configurations.
Transaction line fields
Orb Rev Rec Start Datecustcol_orb_rev_rec_start_dateRepresents the line item service period start date. Mapped to the revenue element start date via revenue field mapping.
Orb Rev Rec End Datecustcol_orb_rev_rec_end_dateRepresents the line item service period end date. Mapped to the revenue element start date via revenue field mapping.
Orb List Ratecustcol_orb_list_rateRepresents unadjusted subtotal amount before adjustments have been applied.
Orb Discount Percentagecustcol_orb_discount_percentageRepresents the percentage discount adjustment configured in Orb.
Orb Discount Amountcustcol_orb_discount_amountRepresents the amount discount adjustment configured in Orb.
Orb Discounted Ratecustcol_orb_discounted_rateThis is a derived value calculated outside of Orb. Represents the per-unit adjusted rate.
Orb Discounted Amountcustcol_orb_discounted_amountThis is a derived value calculated outside of Orb. Represents the per-line adjusted subtotal.
Orb Coupon Appliedcustcol_orb_coupon_appliedRepresents the coupon amount discount adjustment configured in Orb.
Orb Maximum Adjustmentcustcol_orb_max_adjustRepresents the subtotal delta above the maximum adjustment configured in Orb.
Orb Minimum Adjustmentcustcol_orb_min_adjustRepresents the minimum adjustment configured in Orb.
Orb Credit Block IDcustcol_orb_credit_block_idRepresents the credit block ID that triggered the creation of this NetSuite customer deposit. Only applicable for recognizing prepaid credit drawdown.
Orb Prepaid Credit Typecustcol_orb_prepaid_credit_typeRepresents whether this record corresponds to an allocation or manual purchase credit block in Orb. Only applicable for recognizing prepaid credit drawdown.
Orb Credit Expiration Datecustcol_orb_credit_expiration_dateRepresents the expiration date configured on the corresponding credit block in Orb, if applicable. Only applicable for recognizing prepaid credit drawdown.
Orb Line Item IDcustcol_orb_line_item_idRepresents the corresponding Orb line item ID to help with debugging.

​
Step 3: Generate your NetSuite connection credentials

You will need to do this with a user with Administrator access to your NetSuite account.

​
1. Verify the script deployment from the bundle

  1. Navigate to Customization > Scripting > Script Deployments.
  2. Find the RESTlet deployment installed by the bundle and click on ‘View’.
    Netsuite5
  3. Verify the deployment Status is Released.
  4. Click on the name of the script, then note the URL — you will need it for the installation step.
Netsuite6

​
2. Create an integration record

The integration record identifies the external application that will connect to your NetSuite account.
  1. Navigate to Setup > Integration > Manage Integrations > New.
  2. Enter a Name for the integration (e.g. “Orb NetSuite Integration”).
  3. Under the Token-based Authentication section:
    • Uncheck TBA: Authorization Flow
    • Uncheck Token-Based Authentication
  4. Under the OAuth 2.0 section:
    • Uncheck Authorization Code Grant
    • Check Client Credentials (Machine to Machine) Grant
  5. Under Scope, check the following:
    • RESTlets
    • REST Web Services
  6. Click Save.
Netsuite 7
  1. After saving, NetSuite displays the Consumer Key / Client ID under the Client Credentials section. Copy this value and store it securely — it is shown only once and cannot be retrieved later.
Netsuite8

​
3. Generate a certificate key pair

In this step you’ll use your computer’s terminal to create two files: a private key and a self-signed certificate. This is a one-time operation — if anything goes wrong, you can delete the files and start over.Before you begin, you need OpenSSL available in your terminal. macOS and most Linux distributions include it by default. On Windows, use Git Bash (bundled with Git for Windows, which includes OpenSSL), WSL, or install OpenSSL and ensure it is on your PATH. 1. Create a folder and open a terminal in it Create a new folder anywhere you’ll remember — your Desktop works fine. For example, create one called netsuite-keys. Then open a terminal inside that folder so the files you generate end up there:
  • macOS: In Finder, right-click the folder and choose New Terminal at Folder. (If you don’t see this option, enable it under System Settings > Keyboard > Keyboard Shortcuts > Services > Files and Folders > New Terminal at Folder.)
  • Windows: In File Explorer, right-click inside the folder and choose Open in Terminal or Open Git Bash here.
  • Any OS (fallback): Open your terminal app, type cd (with a trailing space), drag the folder from your file browser onto the terminal window, and press Enter.
2. Run the OpenSSL commands Copy each command below, paste it into the terminal right after the prompt (% on macOS, $ on Linux/Git Bash, PS> on PowerShell), and press Enter. Run them one at a time. 
openssl ecparam -name prime256v1 -genkey -noout -out private-key.pem

openssl req -new -x509 -key private-key.pem -out cert.pem -days 730
The second command will prompt you for certificate details (country, organization name, email, etc.). Press Enter at every prompt to accept the defaults — these values are not used by the integration, so it doesn’t matter what they are. 3. Confirm the two files were created If the commands succeeded, your folder now contains two files:
  • private-key.pem — Your private key. You will base64-encode this and share it when installing the integration.
  • cert.pem — Your public certificate. You will upload this to NetSuite.
Open the folder in Finder (macOS) or File Explorer (Windows) to confirm both files are there. If you can’t see them, search your computer for cert.pem — the files were created in whichever folder your terminal was open in.
If anything looks wrong — missing files, error messages, accidentally hit Enter too many times — just delete the files and run the commands again. The keys aren’t registered anywhere until you upload cert.pem to NetSuite, so there’s no risk in starting over.
4. Base64-encode the private key Run the command below to print a base64-encoded version of your private key directly in the terminal. Use the version that matches your environment: macOS (Terminal) 
base64 -i private-key.pem
Linux, Git Bash, or WSL 
base64 -w 0 private-key.pem
Windows (PowerShell) From the directory that contains private-key.pem: 
[Convert]::ToBase64String([IO.File]::ReadAllBytes((Resolve-Path 'private-key.pem')))
Copy the encoded string (a long single line, e.g. starting with LS0tLS1CRUdJTiBFQyBQUklWQVRFIEtFWS0tLS0t...). It will be required during the installation process.

​
Step 4: Create an integration user and authorize a M2M connection

Create an integration user We strongly recommend creating a dedicated NetSuite integration user for the Orb integration, rather than connecting with a personal administrator account. This keeps access predictable over time, and makes it easier to audit which changes are driven by the integration.
  1. Create a new NetSuite user intended only for the Orb integration (for example, orb-integration@yourcompany.com).
  2. Assign an appropriate role to this user:
    1. For fastest setup, you can assign the pre-defined Orb Integration Role that ships with the Orb NetSuite Integration bundle (recommended).
      1. Navigate to Setup > Users/Roles > User Management > Employees (or Lists > Employees).
      2. Find and edit the employee record you want the integration to run as. This can be an existing user or a dedicated integration user.
      3. Go to the Access tab.
      4. In the Roles subtab, click Add.
      5. Select the custom role from the dropdown.
      6. Click Save.
    2. If your security team requires stricter scoping, you can instead create a custom role based on NetSuite’s permissions model, using our Required permissions section as a baseline.
Use this user to authorize the Orb → NetSuite connection during integration setup. Any future permission changes can then be made by editing this role, without touching individual employee accounts. Create a machine-to-machine certificate mapping
  1. Navigate to Setup > Integration > OAuth 2.0 Client Credentials (M2M) Setup.
  2. Click Create New.
  3. Configure the following fields:
    1. Entity: Select the integration user (from the previous step)
    2. Role: Select the custom role that the bundle installed. Please note that the role must include the Log in Using OAuth 2.0 Access Tokens permission.
    3. Application: Select the integration record you created.
    4. Certificate: Upload the cert.pem file you generated.
  4. Click Save.
Netsuite9
  1. Copy the Certificate ID from the list — you will need this value when installing the integration.
Netsuite10
Check that the Valid Until date for the certificate is two years in the future. NetSuite allows a maximum validity of 730 days.

​
Step 5: Configure the integration in Orb

Once your NetSuite bundle is installed and the dedicated integration user is ready, you’ll complete the connection from within Orb. This step links your Orb account to your NetSuite environment using that integration user and enables the asynchronous, one‑way sync from Orb → NetSuite.

​
1. Navigate to the NetSuite integration in Orb.

  1. Go to Settings > Integrations > Accounting.

​
2. Start the connection flow.

  1. Click Connect.
  2. When installing the integration, you will be prompted for a number of inputs:
Netsuite11
Here is where to find each value:
InputWhere to find it
Client IDThe Consumer Key saved.
Certificate IDThe Certificate ID saved.
Private KeyBase64-encoded contents of private-key.pem.
Account IDYour NetSuite URL (e.g. https://1234567.app.netsuite.com → Account ID is 1234567).
RESTlet Deployment URLThis is printed out in the Deployments tab of the script, and looks like /app/site/hosting/restlet.nl?script=3045&deploy=1.
Sandbox accounts: If you are connecting a sandbox account, your Account ID may contain an underscore and suffix (e.g. 1234567_SB1). Provide it exactly as shown in your NetSuite URL or Company Information page.
  1. Select and accept all permissions.

​
3. Configure sync behavior and mappings.

  1. After establishing a successful connection, define how Orb maps to your NetSuite account.
    1. Subsidiary → select which entity transactions are created in.
    2. Location → select a value if this segment is required on a NetSuite transaction. Else, the record will fail to sync.
  2. Select the tax override code configured above, if syncing taxes applied to invoices issued from Orb.
  3. Select a bank account per currency to determine where payments received in Orb should be recorded.
  4. Define the scope of transactions synced from Orb, using controls like minimum invoice date or amount.
  5. Configure how NetSuite handles transactions synced from Orb – enable to create sales orders and RMAs.
  6. Map items.
    1. A NetSuite Item controls how a line item behaves financially, including which GL account it impacts, how revenue is recognized, and how it’s handled operationally. This mapping determines how Orb line items behave when synced to NetSuite.
    2. The integration supports netSuite items of type = Non-Inventory For Sale.
  7. Map customer metadata.
    1. Any customer-level metadata created before a customer is synced from Orb to NetSuite can be mapped and synced to NetSuite custom entity fields upon creation. 
    2. This lets you keep key attributes (for example, account owner, billing segment, go‑live date, or internal IDs) aligned between systems without manual re-entry.
    3. This is a one-time initial sync upon customer creation in NetSuite. 
      1. Subsequent updates to this field in Orb are not synced to NetSuite.
      2. New customer-level metadata added to the Orb customer record does not update in NetSuite.
  8. Review the configuration summary, then save. The review step summarizes the NetSuite setup, accounting settings, chart of accounts, and Orb-to-NetSuite mappings from the previous steps.
Any unmapped item will fail to sync to NetSuite.

​
Step 6: (Optional) Manually configure custom records required for credit drawdown.

In order for Orb’s integration to recognize prepaid credit drawdown in NetSuite, the following GL accounts and items must be manually created and configured in NetSuite.

​
Custom GL accounts

Setup > Accounting > Chart of Accounts > New.
Account NameAccount TypePurpose
Deferred Revenue - Prepaid CreditsDeferred RevenueTracks the total prepaid credit balance available for usage, reduced as credits are consumed and cleared when credits expire.
Prepayment Clearing - Prepaid CreditsOther Current LiabilityUsed to enable Customer Deposit application. Always offsets Customer Deposits liability and collapses to zero at expiration.
Deferred Revenue - Usage ClearingDeferred RevenueTemporary account that serves as an intermediary for journal entries, always netting to zero after each transaction.
Revenue - Expired Prepaid CreditsIncomeBreakage/expiration revenue. Credited by ARM at month-end close when credit expiration is recognized.
Deferred Revenue - Expired Prepaid CreditsDeferred RevenueHolds the balance of expired prepaid credits for recognition.
Validate your Customer Deposits GL accountRelatedly, while not a custom GL account you need to configure, a Customer Deposits GL account is required for the credit drawdown behavior to function as expected.To check:
  1. Navigate to Setup → Accounting → Chart of Accounts
  2. Confirm that an account with Name = Customer Deposits and Type = Other Current Liability exists. If it does, no further action is needed.
To create one, if needed:
  1. Navigate to Transactions → Customers → Record Customer Deposit
  2. Populate the following fields:
    • Customer — select any active customer, preferably a test customer
    • Payment Amount — enter a nominal amount (e.g. $0.01)
    • Any additional mandatory fields required by your NetSuite configuration
  3. Click Save
  4. Navigate back to Setup → Accounting → Chart of Accounts and confirm the Customer Deposits (Other Current Liability) account now appears.
  5. Once confirmed, navigate back to the test Customer Deposit record and delete it. The GL impact will be automatically reversed upon deletion.

​
Custom revenue recognition rule

Lists > Accounting > Revenue Recognition Rule > New.
RuleRequirements
Custom Rev Rec Rule
  • Name: Credit Expiration
  • Recognition Method: Straight-line, by even periods
  • Amount Source: Event-Percent based on amount
  • Rec Rec Start Date Source: Event Date
  • Rev Rec End Date Source: Event Date
  • End Date Change Impact: Update Remaining Periods Only

​
Custom recognition event type

Lists > Accounting > Custom Recognition Event Types > New.
ObjectRequirements
Custom Recognition Event Type
  • Name: Prepaid Credit Expiration
  • Create Recognition Plan Per Event checked

​
Custom payment method

Setup > Accounting > Accounting Lists > Payment Method > New.
ObjectRequirements
Custom Payment Method
  • Name: Prepaid Credits
  • Type = Offline
  • Group with Undeposited Funds checked

​
Items

Lists > Accounting > Items > New.
Item NameRequirements
Prepaid Credit
  • Item type: Service for Sale
  • Accounting
    • Income account = Revenue - Expired Prepaid Credits
    • Deferred revenue account = Deferred Revenue - Usage Clearing
  • Revenue Recognition / Amortization
    • Allocation Type = Exclude
    • Revenue Recognition Rule = Credit Expiration
    • Rev Rec Forecast Rule = Credit Expiration
    • Create Revenue Plans On = Prepaid Credit Expiration
  • Item type: Service for Sale
Note: you’ll need to configure a credit item per credit currency / credit type. (Ex: USD credits vs. CR credits)
Prepaid Credit Expiration
  • Item type: Service for Sale
  • Accounting
    • Income account = Revenue - Expired Prepaid Credits
    • Deferred revenue account = Deferred Revenue - Usage Clearing
  • Revenue Recognition / Amortization
    • Allocation Type = Exclude
    • Revenue Recognition Rule = Default Standard
    • Rev Rec Forecast Rule = Default Standard
    • Create Revenue Plans On = Billing
  • Item type: Service for Sale
Allocation ExpirationSame as “Prepaid Credit Expiration”.