Skip to content
NesoTMS
Get started

Documentation

Set up NesoTMS with NetSuite, step by step

This guide takes a NetSuite administrator from a new NesoTMS company to a connected account that lists orders and writes labels back. It names every NetSuite screen, the permissions of the NesoTMS Connector role, and the exact item fulfillment fields NesoTMS changes, so your team can approve the setup before anything is connected.

Last updated

Before you start

  • A NesoTMS company where you are an administrator. Only administrators connect NetSuite, install the connector and add carrier accounts.
  • NetSuite administrator access, to turn on features and create the integration record and access token. If that is someone else, they can do the NetSuite parts of steps 1 to 6 and send you the values for step 7.
  • Your NetSuite account ID, found under Setup › Company › Company Information. A sandbox account ID ends in _SB1, _SB2 and so on.
  • A decision about which NetSuite record you ship from: item fulfillments (the default) or sales orders. NesoTMS imports one type per company.
  • Later, for labels: your own carrier accounts, and optionally a computer for a shipping station.

The setup, in order

Steps 1 to 3 install the NesoTMS connector, the part that lives inside NetSuite. Steps 4 to 7 connect NesoTMS to it. Steps 8 to 11 choose what NesoTMS reads and turn it on.

  1. 1

    Turn on the NetSuite features

    Go to Setup › Company › Enable Features. An administrator is required. On the SuiteCloud tab turn on Custom Records, Server SuiteScript, SuiteCloud Development Framework, OAuth 2.0 and REST Web Services. On the Transactions tab turn on Advanced Shipping, which the connector requires.

  2. 2

    Install the connector

    In NesoTMS, open the NetSuite setup page and choose NesoTMS installs it for you. Enter your account ID and choose Create my certificate, then download the certificate file, named nesotms-ACCOUNT.pem. In NetSuite go to Setup › Integration › Manage Authentication › OAuth 2.0 Client Credentials (M2M) Setup and choose Create New. Set Entity to yourself, Role to Administrator, Application to SuiteCloud Development Integration, and Certificate to the downloaded file. Save, copy the Certificate ID NetSuite shows, and paste it into NesoTMS. If SuiteCloud Development Integration isn't in the list, contact NesoTMS. If setup says the install isn't available for your company yet, contact NesoTMS too. If the connector is already in your account, choose The connector is already installed and go on to step 4.

  3. 3

    Watch the install, then clean up

    NesoTMS shows four stages: waiting for the installer, signing in to NetSuite, checking the account, and installing the connector. It signs in once with your certificate, installs the connector and deletes its key. The certificate is valid for seven days, and you can revoke it in the same NetSuite list when the install says it is done. Then give the NesoTMS Connector role to the employee who will connect NesoTMS.

  4. 4

    Create the integration record

    Go to Setup › Integration › Manage Integrations › New. Name it NesoTMS, check Token-based authentication, and save. Copy the consumer key and consumer secret now: NetSuite shows them once.

  5. 5

    Create the access token

    Go to Setup › Users/Roles › Access Tokens › New. Choose the NesoTMS application, the user who runs the integration and that user's role. Save, then copy the token ID and token secret.

  6. 6

    Copy the RESTlet URL

    Go to Customization › Scripting › Script Deployments, open the NesoTMS RESTlet deployment, customdeploy_xtms_rl_service, and copy its External URL. The role on the access token has to be in that deployment's audience.

  7. 7

    Connect and test

    In NesoTMS, paste the account ID, the External URL and the four values: the consumer key and secret, and the token ID and secret. They are 64-character values, and the same value can't go in two fields. Choose Save and test. The result shows the NetSuite account and environment, the user and role the token runs as, and the RESTlet build. The keys are encrypted before they are stored and are never shown again.

  8. 8

    Choose what to import

    Choose Item fulfillments or Sales orders, then the statuses to show: Picked and Packed for fulfillments, or Pending Fulfillment, Partially Fulfilled and Pending Billing/Partially Fulfilled for orders. Optionally set the declared value minimum, a default country of origin for Canada customs lines, and which carrier service each of your NetSuite ship methods should use. Changing the record type later clears the mapping and turns the import off.

  9. 9

    Map the fields

    Answer Do your NetSuite records include box sizes? Choose From package lines if fulfillments carry package lines with sizes, so the ship page starts with those boxes. Choose Packers enter them if not. Each NesoTMS field then maps to a standard NetSuite field, to Not mapped, or to a custom field ID. Custom field choices are saved, but the connector doesn't read them yet.

  10. 10

    Review and turn on

    The review step summarizes each choice with Edit links and previews the first 10 records your settings match: number, date, customer, ship-to, ship method and status. Nothing is stored by the preview. Choose Turn on, and the Packing Station, the Clerk Station and the ship pages switch from sample settings to yours.

  11. 11

    Add carriers and ship a first label

    Connect your carrier accounts on the Carriers page (UPS, FedEx, FedEx Freight or USPS) and, if you want printing without a dialog, set up a shipping station. A carrier account set to Test never changes NetSuite, so you can try a purchase safely. For a first real check, buy one label and open that fulfillment in NetSuite to confirm the tracking number, package lines, cost and Shipped status.

Permissions of the NesoTMS Connector role

These are the permissions defined in the connector's role file, customrole_neso_connector. The role is not a core administrator role and is not limited to web services.

Permissions of the NesoTMS Connector role
PermissionLevelWhat it covers
Item fulfillments (TRAN_ITEMSHIP)EditReading fulfillments and writing the label results back.
Sales orders (TRAN_SALESORD)ViewOrder lists and lines, PO numbers, and prices for the declared value and customs.
Customers (LIST_CUSTJOB)ViewCustomer names.
Items (LIST_ITEM)ViewItem weights, descriptions, HS codes and countries of manufacture.
Locations (LIST_LOCATION)ViewShip-from addresses.
Subsidiaries (LIST_SUBSIDIARY)ViewThe ship-from fallback in accounts with subsidiaries.
XTMS Carrier Account, XTMS Carrier Service and XTMS Shipment (custom records)FullThe carrier records and the label receipts the connector keeps.
NesoTMS Settings (custom record)ViewThe connector's own settings.
REST Web Services (ADMI_RESTWEBSERVICES)FullPart of the role definition.
Log in using OAuth 2.0 access tokens (ADMI_LOGIN_OAUTH2)FullPart of the role definition.

The connector adds this role to the RESTlet deployment's audience. If you installed the scripts by hand, add the role of your access token to the deployment's audience yourself.

Exactly what NesoTMS writes to an item fulfillment

One write-back runs when a label is bought and another when a label is voided. They set values instead of adding to them, so repeating one is safe. The NetSuite integration page explains the same behavior in plain terms. The fulfillment is saved in standard mode with the mandatory-field check off.

Exactly what NesoTMS writes to an item fulfillment
FieldWhen a label is boughtWhen a label is voided
Shipping cost (shippingcost)The label's price: the negotiated rate when the carrier returns one, otherwise the published rate. Not touched when the carrier returns no price, as with FedEx Freight bookings.Not touched.
Package list: UPS, FedEx, USPS or the generic Package listThe list that already has lines is used. If none has lines, the first list the record has is used, the UPS list when it exists. Its lines are replaced with one line per package bought.Only the voided label's tracking numbers are blanked, in whichever list holds them. Lines keep their weights and sizes.
Package weightSet on every line.Not touched.
Package length, width and heightSet when all three are known. A size the list refuses is skipped and logged, never a failed update.Not touched.
Package descriptionThe carrier and service name, cut to 35 characters, on lists that have a description column. The FedEx list has none.Not touched.
Package tracking numberSet on every line.Blanked for the voided label.
Ship status (shipstatus)Set to Shipped (C). If NetSuite refuses the status or the save, the rest is saved without it and NesoTMS says so.Set to Packed (B), only if it is Shipped now and no other active label remains.
Ship method, items, quantities, inventory detail, addresses, memo, declared or insured valueNot touched.Not touched.

On accounts that have the connector's receipt fields, each NesoTMS label is also recorded as an XTMS Shipment record with source set to engine: the fulfillment, carrier, environment, status, shipment ID, tracking numbers, service, currency, label format and cost. A void marks it voided with the time. Label files stay in NesoTMS.

What never reaches NetSuite

Rates and quotes are not written anywhere in NetSuite. Neither are labels bought on carrier accounts set to Test, FedEx Freight estimates, USPS sandbox labels, or the carrier keys you add in NesoTMS. NesoTMS doesn't create or delete item fulfillments, doesn't edit sales orders, and doesn't change the addresses on your records.

If something doesn't work

  • Test connection reports a rejected login: NetSuite refused the token. Copy the four values again (NetSuite shows the secrets only once) and check that the access token's role is the one you meant.
  • Test connection says the role isn't in the deployment's audience: open the RESTlet deployment under Customization › Scripting › Script Deployments and add the role of the access token to its audience.
  • Test connection reports a wrong script or deploy: copy the External URL from the NesoTMS RESTlet deployment again. NesoTMS keeps only its script and deploy parameters and checks that it belongs to your account ID.
  • The install stops because the connector is already in the account: NesoTMS doesn't overwrite an existing connector. Use The connector is already installed and connect with the four values.
  • The install failed after you pasted the Certificate ID: NesoTMS shows the reason with the ID filled in. Correct it and try again, or, if the certificate expired, start over with a new one.
  • The Clerk Station is empty: it lists item fulfillments in Packed status only, so check that the fulfillments are packed in NetSuite. The Packing Station is empty: check the record type and statuses chosen in the Import step, and use the preview to see what NetSuite returns for those settings.
  • NesoTMS says your NetSuite settings couldn't be loaded: choose Try again. The pages never fall back to sample settings.

Turning off and disconnecting

Turn off on the setup page stops NesoTMS from using your import settings and keeps them. Disconnect deletes the saved keys and settings in NesoTMS. In NetSuite, revoke the access token, and if you want the connector gone, delete its scripts and records by hand: removing an SDF-installed connector can't be done from NesoTMS. Labels already bought keep their results on the item fulfillments.

NetSuite setup questions

Does NesoTMS need the Administrator role all the time?

No. Administrator is used once, for the certificate that installs the connector, and NesoTMS deletes its key afterwards. Day to day it signs in with the access token you created, using that token's role.

Can I try the setup in a NetSuite sandbox first?

Yes. Sandbox account IDs such as 1234567_SB1 are accepted, and carrier accounts set to Test never update NetSuite.

Where do the NetSuite keys go?

They are encrypted with AES-256-GCM before they are stored, never shown again and never returned to the browser. Only administrators can save, replace or test them.

Can I use custom fields?

You can save a custom field ID in the field mapping, but the connector reads only standard NetSuite fields today, so a custom choice has no effect yet.

Related pages

Ship more. Click less.

Set up in under 10 minutes.

Or try the demo first