/
NetSuite Integration

NetSuite Integration

Overview

In this page you will find information about how the PracBill NetSuite accounting integration works, what it does and how the elements tie together.

It's VERY important you understand this before enabling it.

What Does the Integration Do?

The NetSuite integration automatically synchronizes the following between PracBill and NetSuite:

✅ Customers - Synced from PracBill to NetSuite when invoices are created
✅ Invoices - Authorized invoices pushed from PracBill to NetSuite
✅ Payments - Two-way sync between PracBill and NetSuite
✅ Chart of Accounts - Imported from NetSuite to PracBill

Web API Setup Requirements

Before you can enable the NetSuite integration in PracBill, you must configure the Web Services API in your NetSuite account and collect specific credentials.

Step 1: Find Your NetSuite Account ID

This is critical - you'll need this to connect PracBill to NetSuite.

Your NetSuite Account ID can be found in several ways:

  1. From your NetSuite URL:

    • When logged into NetSuite, look at your browser URL

    • Format: https://[ACCOUNT_ID].app.netsuite.com/...

    • Your Account ID is everything before .app.netsuite.com

    • Example: If your URL is https://1234567.app.netsuite.com/, your Account ID is 1234567

    • For sandbox accounts, it may include -sb1 or similar (e.g., 1234567-sb1)

  2. From NetSuite Setup:

    • Navigate to Setup > Company > Company Information

    • Look for Account ID field

    • Copy the complete Account ID including any suffix

Write this down - you'll need to enter it into PracBill later.

Step 2: Enable Web Services Features

  1. Navigate to Setup > Company > Enable Features

  2. Go to the SuiteCloud tab

  3. Ensure the following features are enabled:

    • Web Services

    • REST Web Services

    • Token-Based Authentication (or OAuth 2.0)

  4. Click Save

Step 3: Create an Integration Record

This generates the OAuth credentials (Client ID and Client Secret) needed for PracBill to connect.

  1. Go to Setup > Integration > Manage Integrations > New

  2. Fill in the following:

    • Name: "PracBill Integration" (or any name you prefer)

    • State: Enabled

  3. Under Authentication section:

    • Check OAuth 2.0

    • ⚠️ CRITICAL: Set OAuth 2.0 Consent Policy to "Ask First Time"

      • ❌ NOT "Always Ask"

      • ❌ NOT "Never Ask"

      • ✅ MUST be "Ask First Time" (this is critical for OAuth to work correctly)

    • ⚠️ CRITICAL: Check User Credentials checkbox

      • This checkbox MUST be enabled for OAuth authentication to work

  4. Under Callback/Redirect URL:

    • Redirect URI: https://billing-api.pracbill.com.au/netsuite/callback

    • If using a different PracBill domain, replace with your actual domain ( i.e. on premise version )

    • The URI must match exactly (including https://)

  5. Under Scope:

    • ✅ Enable REST Web Services (required)

    • ❌ Leave RESTlets unchecked (not required)

    • ❌ Leave SuiteAnalytics Connect unchecked (not required)

  6. Click Save

After saving, NetSuite will display:

  • Consumer Key (also called Client ID) - Copy this (64 characters)

  • Consumer Secret (also called Client Secret) - Copy this (64 characters)

⚠️ IMPORTANT: The Consumer Secret is only shown once. Copy it immediately and store it securely.

Step 4: Set Required Permissions

The user account that will authorize the integration must have a role with the following permissions:

Transactions:

  • Customers: View, Create, Edit

  • Invoices: View, Create, Edit

  • Customer Payments: View, Create, Edit

  • Customer Deposits: View, Create, Edit (for overpayments)

Lists:

  • Chart of Accounts: View

  • Items: View, Create

  • Departments: View (if using department mapping)

  • Subsidiaries: View (for multi-subsidiary setups)

  • Currencies: View

Setup:

  • REST Web Services: Full

  • User Access Tokens: Full (if using token-based auth)

Recommended: Create a dedicated "PracBill Integration" role with exactly these permissions.

Step 5: Credentials Checklist

Before proceeding to PracBill, ensure you have collected:

Credential

Where to Find

Example Format

Credential

Where to Find

Example Format

NetSuite Account ID

Company URL or Setup > Company > Company Information

1234567 or 1234567-sb1

OAuth Client ID

From Integration Record (Consumer Key)

ab6f21066291280d19ae37239e1ac69d2aa1a9aa... (64 chars)

OAuth Client Secret

From Integration Record (Consumer Secret) - shown only once

3fb0539d6e6caa53c67dd29c22229f81923511f7... (64 chars)

Step 6: Connect PracBill to NetSuite

  1. In PracBill, navigate to Company > Departments

  2. Select your department and scroll to the NetSuite integration section

  3. Enter the credentials you collected:

    • NetSuite Account ID (e.g., 1234567-sb1)

    • OAuth Client ID (the Consumer Key - 64 characters)

    • OAuth Client Secret (the Consumer Secret - 64 characters)

  4. Click Connect to NetSuite

  5. You'll be redirected to NetSuite to authorize the connection

  6. Log in with your NetSuite credentials (must be a user with required permissions)

  7. Review and approve the requested permissions

  8. You'll be redirected back to PracBill

Step 7: Verify Connection

After successful authorization, PracBill will automatically:

  • ✅ Test the connection to NetSuite

  • ✅ Import your Chart of Accounts

  • ✅ Verify permissions are correctly set

  • ✅ Create a generic service item in NetSuite for invoicing

You should see a success message: "Successfully connected to NetSuite! Data synchronization has been queued and will complete in the background."

Troubleshooting Connection Issues

If you encounter connection errors, verify:

"Invalid Grant" Error:

This is the most common OAuth error. To resolve:

  • ✅ Check OAuth 2.0 Consent Policy is set to "Ask First Time" (NOT "Always Ask")

  • ✅ Verify User Credentials checkbox is enabled in the NetSuite integration record

  • ✅ Confirm the Redirect URI in NetSuite matches your PracBill domain exactly

  • ✅ Ensure the integration record is enabled in NetSuite

  • ✅ Double-check the Consumer Key and Secret are copied correctly (no extra spaces)

  • ✅ Try creating a new integration record in NetSuite with the correct settings

  • ✅ Clear your browser cache and cookies, then try again

Invalid Account ID:

  • Ensure you copied the complete Account ID including any suffix (-sb1, etc.)

  • Check for extra spaces or characters

  • Verify the account is active

OAuth Authorization URL Shows {accountId} Placeholder:

  • This indicates a system configuration error

  • Contact your PracBill system administrator

  • The server's .env file may have been incorrectly modified

Token Expired or Invalid:

  • The connection may need to be re-authorized periodically

  • Go back to Settings > Accounting Integrations > NetSuite and click Reconnect

Permission Errors:

  • The authorizing user's role must have all required permissions listed in Step 4

  • Check NetSuite audit logs to see which permission was denied

Web Services Not Enabled:

  • Verify REST Web Services are enabled under Setup > Company > Enable Features > SuiteCloud

Optional Configuration

Default Values

You may want to configure these defaults in NetSuite before connecting:

  • Default Subsidiary: If using multi-subsidiary, specify which one PracBill should use

  • Default Currency: Ensure your primary currency matches PracBill's currency

  • Customer Form: Create a custom customer form for PracBill-created customers (optional)

  • Invoice Item: Create a generic "Service" item for catch-all charges (or PracBill will create one)

Multi-Subsidiary Setup

If your NetSuite account uses multiple subsidiaries:

  1. Determine which subsidiary PracBill should create customers and invoices in

  2. Ensure the integration user has access to that subsidiary

  3. Set the default subsidiary in PracBill's NetSuite settings

Sandbox vs Production

Testing in Sandbox:

  • Use your sandbox Account ID (typically ends in -sb1, -sb2, etc.)

  • Create a separate integration record in sandbox

  • Test the full sync process before connecting production

Production Setup:

  • Use your production Account ID (no suffix)

  • Create a new integration record in production NetSuite

  • Never share credentials between sandbox and production

Payments

From NetSuite to PracBill (Import)

PracBill automatically imports customer payments from NetSuite that are applied to invoices. This ensures your payment records in PracBill stay synchronized with NetSuite.

What Gets Imported:

  • ✅ Customer payments that are applied to invoices already synced from PracBill

  • ✅ Payment amount, date, and payment method

  • ✅ Payment linkage to the correct invoice(s) in PracBill

  • ✅ Any notes or memos attached to the payment in NetSuite

How Payment Matching Works:

When PracBill imports a payment from NetSuite, it:

  1. Identifies which NetSuite invoice(s) the payment is applied to

  2. Matches those NetSuite invoices to the corresponding PracBill invoices

  3. Creates a payment record in PracBill and links it to the correct invoice(s)

  4. Records the payment with type "NetSuite" so you know its origin

Important Notes:

  • Only payments applied to invoices that were originally created from PracBill will be imported

  • If a payment in NetSuite is applied to multiple invoices, PracBill will link the payment accordingly

  • Payment method information from NetSuite is stored in the payment notes in PracBill

  • Payments are identified by their NetSuite internal ID to prevent duplicate imports

Sync Schedule:

PracBill will pull payments from NetSuite at 6:00 AM AEST daily.

What About Overpayments?

If you have a payment option that is set up with a Bank Account in NetSuite, PracBill will also pull in any overpayments (customer deposits) that have been recorded against customers whose invoices were created from PracBill.

From PracBill to NetSuite (Export)

You can configure PracBill to push payments back to NetSuite. This is useful when you collect payments through PracBill payment gateways or record manual payments in PracBill.

Requirements:

To activate payment export to NetSuite, you need to:

  1. Create a clearing account in NetSuite (not a bank account)

  2. Set this clearing account as the payment option's "Bank or Clearing Account" in PracBill

Why Use a Clearing Account?

Using a clearing account allows you to handle:

  • Payment gateway fees that are deducted before funds reach your bank account

  • Batch settlements where multiple payments are deposited as a single lump sum

  • Proper reconciliation between PracBill gateway payments and actual bank deposits

Reconciliation Process:

  1. PracBill pushes individual payments to the clearing account in NetSuite

  2. When funds are actually deposited to your bank, you reconcile the bank deposit in NetSuite

  3. Match the bank deposit to the clearing account balance to complete the reconciliation

⚠️ Important: You must use a clearing account, not a bank account, to push payments to NetSuite. This ensures proper separation between payment recording and bank reconciliation.

Sync Schedule:

PracBill will push payments to NetSuite at 9:00 PM AEST daily.

Contacts

From PracBill to NetSuite

We sync our contacts from PracBill to NetSuite as we invoice them. The Account Number is the PracBill Customer ID. If there is an existing customer with that Account Number in NetSuite we will use that to map to the PracBill Customer.

When an invoice is pushed to NetSuite there is some validation that happens, and that can return some validation issues, the common ones are listed below.

Important Notes

Inactive Contacts

If you have made a contact inactive in NetSuite, then we have a problem. The most common error that will indicate this is:

The Account Number already exists

Validation Error: The contact with the specified contact details has been marked inactive. The contact must be reactivated before creating new invoices.

We have code in place to attempt to recover from that, however inactive contacts prevent that. You will need to reactivate the contact in NetSuite to resolve this.

Validation Issues

The Account Number already Exists

This happens when there has been an update on the NetSuite side for the customer id. We then call NetSuite to get the current Contact Id for that Customer ID and update it on our side, so all future invoices are associated with that Contact.

An existing contact could not be found using the specified contact details

This happens when a Contact has been deleted in NetSuite and it's ended up out of sync in Pracbill, we then reset the NetSuite Contact in Pracbill and resync the invoice to NetSuite.

Invoices

From PracBill to NetSuite

Authorized invoices are automatically pushed to NetSuite. Only invoices with the status of Authorized will sync to NetSuite.

When an invoice is pushed:

  • The customer is automatically synced to NetSuite if they don't already exist

  • Line items are created for all services, usage, and products on the invoice

  • Service type items are automatically created in NetSuite if they don't already exist

PracBill will push invoices to NetSuite at 9:00 PM AEST daily.

Chart of Accounts

When you first integrate NetSuite, we'll automatically import all your chart of accounts so that you can select these against the appropriate fields in PracBill.

This is the only time we'll automatically sync the Chart of Accounts. However, if you've added/removed some General Ledger codes (GL Codes), you may find that you need to re-sync this manually.

Support Issues

Your connection to NetSuite failed

This issue occurs when the connection from the original user has been removed in NetSuite or that user has been deleted. To verify, there is an alert in the department settings.

To resolve, it's as simple as reconnecting your NetSuite account. Your previous mappings will still all be there, so you won't have to do anything, it will just resume from when it failed.

GL Code Errors

If you receive errors about missing GL codes, ensure that you have:

  1. Imported your Chart of Accounts from NetSuite

  2. Assigned GL codes to all your service types

  3. Assigned GL codes to all your products

Without proper GL code mapping, NetSuite may reject invoices.

Integration Record Disabled

If the integration record in NetSuite is disabled:

  1. Go to Setup > Integration > Manage Integrations

  2. Find the "PracBill Integration" record

  3. Edit and set State to Enabled

  4. Save

  5. Reconnect in PracBill

Expired OAuth Tokens

OAuth tokens expire periodically. If you see authentication errors:

  1. PracBill will attempt to automatically refresh the token

  2. If automatic refresh fails, you'll need to reconnect manually

  3. Go to Settings > Accounting Integrations > NetSuite and click Reconnect

Payment Import Issues

If payments from NetSuite are not appearing in PracBill:

  1. Verify the payment is applied to an invoice in NetSuite

    • The payment must be explicitly applied to an invoice (not just recorded against a customer)

    • Check the payment's "Apply" tab in NetSuite to confirm invoice linkage

  2. Ensure the invoice exists in PracBill

    • The invoice must have been originally created from PracBill and synced to NetSuite

    • Check that the invoice has a NetSuite ID recorded in PracBill

  3. Check sync timing

    • Payment imports run at 6:00 AM AEST daily

    • Allow up to 24 hours for new payments to appear in PracBill

  4. Verify permissions

    • The integration user must have "View" permission for Customer Payments in NetSuite

    • Check that the integration is still connected (not expired)

If payment import continues to fail after checking these items, contact PracBill support with:

  • The NetSuite payment ID

  • The NetSuite invoice ID the payment is applied to

  • The PracBill invoice IID