Custom Shipment Notification for NetSuite

Updated May 13, 2026 20:44

ShipStation includes a default shipment notification workflow or you can write your own custom plugin using NetSuite's plug-in system. A custom plugin is more powerful but requires more maintenance. Use a custom plugin if you need to:

Write to a custom record instead of an ItemFulfillment
Send an internal notification or trigger a workflow when a label is created
Combine tracking data across multiple systems
Run custom validation logic before accepting a shipment

Netsuite OAuth 2.0

This feature is for ShipStation's new NetSuite integration using OAuth 2.0. The Custom Shipment Notification plugin workflow is not supported with the NetSuite Legacy integration.

To create a custom shipment notification plugin you will need to take the following steps in Netsuite:

Write a JavaScript file containing your custom logic.
Upload the JavaScript file to the NetSuite File Cabinet.
Create a plugin implementation record to register it with ShipStation.
Select the implementation record in the Shipment Configuration page.

Write your JavaScript file

To use a custom shipment notification plugin you will need to write a the script using the following structure:

/** 
* @NScriptName Your script name here 
* @NModuleScope Public 
* @NApiVersion 2.1 
* @NScriptType PluginTypeImpl 
*/
define(['N/record', 'N/log'], (record, log) => {
  const processShipmentNotification = (notification) => {
    // Your custom logic here
    return { success: true };
  };
  return { processShipmentNotification };
});

Script Rules:

The function must be named processShipmentNotification for the call to work.
The function must return { success: true } on success, or throw an error on failure. ShipStation will record the error message and mark the notification as failed.
The define([...], (...) =& { ... }) wrapper is required as it tells NetSuite which modules to load.
To generate logs for troubleshooting purposes you will need to add Add N/log to your define(...) imports and use log.debug(...). NetSuite script logs are viewable under Customization > Scripting > Script Execution Log.

Once you have written the custom file you will need to upload it to the NetSuite file cabinet. See the section below for more information on that process.

Upload your JavaScript file to the NetSuite File Cabinet

To upload your file in NetSuite follow the steps below:

Open your NetSuite account and go to Documents > Files > File Cabinet.
Create a folder for your custom scripts (e.g., SuiteScripts/Custom) or navigate to your existing folder if one has already been created.

Do not place files inside the SuiteApps folder as it is managed by ShipStation.
Click New and upload your JavaScript file.
Record the full file path once the upload is complete.

You will need it to create your plugin implementation record in the next section.

Create a Plugin Implementation Record

To create a plugin implementation record in NetSuite follow the steps below:

Open your NetSuite account and go to Customization > Plug-ins > Manage Plug-in Implementations > New.
Fill in the following fields:
- Plug-in Type: Select ShipStation Shipment Notification Plugin
- Name: will be the display name shown in the Shipment Configuration dropdown
- ID: your unique script ID
- Description: this field is optional but recommended
Select your JavaScript file in the Script File field. You should be able to locate it using the file path you recorded in the previous section.
Click Save.

Once you have created the implementation you will need to apply it as your fulfillment strategy. See the section below for more information on that process.

Select the Implementation Strategy for Fulfillment

To begin using your custom notification strategy you will need to select the implementation record you created in the previous section as your fulfillment strategy.

Open your NetSuite account and go to NetSuite tab > Configurations > Shipment Configuration.
Select your custom implementation in the Fulfillment Strategy dropdown.

This drop down will only show registered plugin implementation records. If you do not see your implementation in the drop down you will need to verify that you completed all steps in the section above to create the record.

If you see an error like Module does not exist this indicates the file path entered does not match the file path in the NetSuite File Cabinet. Open the record in your file cabinet to verify the correct file path.
Click Save.

Now anytime ShipStation creates a label, your processShipmentNotification function will be used instead of the default ShipStation notification strategy.

Notification Fields

The notification object your function receives contains the following fields:

FIeld Name	Type	Description
notification_id	string	ShipStation's Notification ID
order_id	string	Netsuite's Internal Sales Order ID Note: To record API calls you can convert this to Number(order_id).
order_number	string	External order number
tracking_number	string	Carrier tracking number
tracking_url	string	Carrier tracking URL
carrier_code	string	Carrier name
ship_date	string	Date shipped (YYY-MM-DD format)
fullfillment_cost	number	Cost of the shipping label
insurance_cost	number	Cost of shipping insurance (if applicable)
items	array	Line items included in the shipment
ship_to	object	Destination address
ship_from	object	Origin address
return_address	object	Return address
notes	array	Notes attached to the shipment
notify_buyer	boolean	Whether the buyer should be notified