Overview
The CIMcloud platform includes a native, bi-directional integration with Oracle NetSuite. CIMcloud hosts, runs, monitors, and maintains the integration as part of the standard offering. Nothing is installed on your servers, and no SuiteApp, bundle, or SuiteScript is installed in your NetSuite account. The integration uses NetSuite’s standard SuiteTalk REST Web Services.
This article is written for NetSuite administrators, IT staff, and ERP partners. It covers:
- Architecture
- APIs and authentication
- Data synced in each direction
- Sync behavior (timing, change detection, initial load)
- Monitoring and error handling
- Scope and limitations
For field-level mappings, see the data-specific articles linked in each section below.
Architecture
The integration has three parts:
- NetSuite – The system of record for customers, items, pricing, inventory, and transactions.
- CIMcloud ERP Sync Tool (also called “ERP Driver”) – A sync service that CIMcloud hosts for each website. It runs as two separate processes: one moves data from NetSuite to CIMcloud, and one moves data from CIMcloud to NetSuite. Because they are separate, a large data load from NetSuite does not delay orders going to NetSuite. See ERP Sync Tool (ERP Driver) Technical Details.
- CIMcloud Platform – The website and its database.
The sync tool starts every connection. It calls NetSuite over HTTPS. NetSuite never calls into CIMcloud, and you do not need to open any inbound network access.
The CIMcloud platform does not query NetSuite live while a user is browsing the site. The sync tool copies NetSuite data into the CIMcloud database on a schedule, and the website reads from that copy. Pricing is calculated by CIMcloud’s high-speed pricing engine, which replicates NetSuite pricing from the synced data. This design has three advantages:
- The website does not depend on NetSuite being available. If NetSuite is down for maintenance, the website keeps running on the last synced data. Orders placed during that time are held and sent when NetSuite is available again.
- API usage is not tied to website traffic. A busy day on the website does not cause more NetSuite API calls, so the integration stays well within NetSuite’s API limits.
- The website is faster. Pages do not wait on NetSuite API responses.
APIs Used
| Direction | NetSuite API | Used for |
|---|---|---|
| NetSuite → CIMcloud | SuiteTalk REST Web Services – SuiteQL query service (/services/rest/query/v1/suiteql) |
Reading customers, items, pricing, inventory, and transaction history |
| CIMcloud → NetSuite | SuiteTalk REST Web Services – REST record service (/services/rest/record/v1/…) |
Creating and updating sales orders, customers, customer deposits, and customer payments |
- SuiteQL is NetSuite’s SQL-based query language. Each data type is pulled with a SuiteQL query that CIMcloud maintains. Results are read in pages of 1,000 records.
- Cost: REST Web Services are included with NetSuite at no extra cost.
- Concurrency: NetSuite limits how many API requests an account can run at the same time, based on its service tier. The sync tool uses only a few concurrent requests. If your account runs many other integrations and reaches its limit, NetSuite’s SuiteCloud Plus license raises it.
- Timeouts: A request to NetSuite that takes longer than 5 minutes is stopped and retried on a later sync cycle.
Authentication and Security
The integration uses NetSuite Token-Based Authentication (TBA), NetSuite’s implementation of OAuth 1.0a. Each API request is signed with HMAC-SHA256. No NetSuite username or password is used, and no login session is kept open.
TBA uses five values:
| Value | Where it comes from in NetSuite |
|---|---|
| Account ID | Setup > Company > Company Information |
| Consumer Key and Consumer Secret | The CIMcloud Integration record (Setup > Integration > Manage Integrations) |
| Token ID and Token Secret | An Access Token that ties the CIMcloud Integration to one NetSuite user and role |
Security points:
- You control access. The integration can only see and change the record types allowed by the role on its access token.
- You can revoke access at any time. Revoking the access token or disabling the Integration record in NetSuite stops the sync immediately.
- Credentials are stored encrypted. CIMcloud stores the consumer secret, token ID, and token secret encrypted. Never send these values by email.
- IP restrictions. If the NetSuite role restricts logins by IP address, contact CIMcloud for the IP addresses to allow.
- Every request is logged in NetSuite. You can review all requests made by the integration in NetSuite. See What You Can See in NetSuite below.
Data Synced from NetSuite to CIMcloud
| Data | NetSuite source |
|---|---|
| Accounts | Customer records and their default billing address |
| Shipping Addresses | Customer address book entries |
| Products | Item records, with the default price from a chosen price level |
| Warehouses | Location records |
| Inventory Levels | On hand, available, committed, backordered, and on-order quantities by item and location |
| Pricing | Price levels (including quantity pricing) and customer-specific item pricing |
| Sales Order History | Sales Order transactions and lines |
| Shipments | Item Fulfillment transactions with tracking numbers |
| Invoices | Invoice and Cash Sale transactions and lines |
| Payments | Customer Payments applied to invoices |
| Credits | Credit Memo transactions |
All sales orders, invoices, and payments sync to the CIMcloud platform, including those entered directly in NetSuite, not just those placed on the website.
Data Synced from CIMcloud to NetSuite
| Data | NetSuite record |
|---|---|
| Sales Orders | Sales Order |
| Customers | Customer (created or updated with each order, when enabled) |
| Order Payments | Customer Deposit, linked to the sales order (credit card and ACH orders) |
| Invoice Payments | Customer Payment, applied to the paid invoices (when configured) |