SuiteScript 2.1 Event Subscriber Script Setup: Files, Subscriptions, and Deployment

SuiteScript 2.1 Event Subscriber script setup requires two coordinated artifacts: a SuiteScript file containing handle(options) and an Event Subscriber SDF object definition that contains the subscriptions. Use this script type when follow-up processing can run asynchronously after the originating record operation completes, rather than during record processing.

TL;DR: Create a SuiteScript 2.1 file that declares @NScriptType EventSubscriber and defines handle(options). Create an Event Subscriber SDF object definition that references that file and contains at least one subscription criterion. Add both artifacts to the same SuiteCloud project, deploy the project to the target account, and test an operation that matches the subscription.

Key takeaways

• Event Subscriber scripts are asynchronous server scripts that run after supported record events and after the originating operation is complete.
• The implementation requires an Event Subscriber script file and an Event Subscriber SDF object definition.
• The script file must use SuiteScript 2.1, declare @NScriptType EventSubscriber, and define handle(options).
• The SDF definition must reference the intended script file and include one or more subscription criteria.
• Use a User Event script instead when work must occur during record processing.

What is a SuiteScript 2.1 Event Subscriber script?

An Event Subscriber script is a server script for asynchronous follow-up work. It runs after a supported event occurs and after the originating operation is complete. Supported record-event examples include creation, update, and deletion of a selected record type. The subscription criteria in the Event Subscriber definition determine which supported events invoke the script.

The timing is the deciding factor. Choose an Event Subscriber when the record operation can complete before the remaining action runs. Documented uses include:

• Sending notifications after subscribed events.
• Updating related data after record changes.
• Starting external or long-running processing without delaying the record operation.

For example, a script can send a notification after an invoice is created. The invoice creation operation completes first, and the subscribed follow-up processing runs afterward.

If your broader automation planning includes record support, see the SuiteScript supported records reference. Keep record and account-ID decisions separate from the Event Subscriber setup contract; SuiteScript IDs for permissions, features, and tasks is related reading for those conventions.

Event Subscriber vs. User Event timing

The documented difference is when each script type runs. User Event scripts run during record processing. Event Subscriber scripts run asynchronously after the supported event and after the originating operation is complete.

Script type	Documented execution timing	Design fit
Event Subscriber script	Runs asynchronously after supported events occur and after the originating operation is complete	Follow-up work does not need to finish before the record operation completes
User Event script	Runs during record processing	Work must occur during record processing

Write the timing requirement before selecting a script type. If this statement is acceptable — “the record operation may complete before this follow-up action runs” — an Event Subscriber may fit. If it is not acceptable, the Event Subscriber timing model does not meet that requirement.

Required SuiteCloud project files

An implementation requires two files in a SuiteCloud project. Treat them as one deployment unit: the script file supplies the behavior, while the SDF definition connects that behavior to subscribed events.

File	Required contents or relationship
Event Subscriber script file	Uses SuiteScript 2.1, declares @NScriptType EventSubscriber, and defines the handle(options) entry point
Event Subscriber SDF object definition	References the script file and includes one or more criteria that identify subscribed events

The script file alone does not express which events invoke the logic. The definition is therefore required, not optional deployment metadata. Before building, decide on the selected record type, the supported event or events of interest, and the follow-up result.

Create the Event Subscriber script file

The script file has two required identifying elements: the Event Subscriber script-type declaration and the entry point. It must use SuiteScript 2.1, declare @NScriptType EventSubscriber, and define handle(options).

@NScriptType EventSubscriber
handle(options)

The handle(options) logic performs the follow-up action associated with the subscribed event. That action can be a notification, a related-data update, or the start of external or long-running processing. Design that logic around asynchronous timing: it runs after the originating operation is complete, not as part of the operation.

For workload-planning context, retain the distinction between general guidance and this script type's documented setup requirements. The SuiteScript usage unit limits guide and NetSuite script execution time limits are useful related references when assessing follow-up work.

Define subscriptions in the Event Subscriber SDF object

The Event Subscriber SDF object definition connects the SuiteScript file to supported events. It must reference the intended script file and include one or more subscription criteria. The criteria determine which supported record events trigger handle(options).

Implementation concern	Artifact responsible
Follow-up processing	Event Subscriber script file
Script-type identity	@NScriptType EventSubscriber in the script file
Callable entry point	handle(options) in the script file
Connection to the script	Event Subscriber SDF object definition
Events allowed to invoke the script	One or more subscription criteria in the SDF definition

Criteria can identify creation, update, or deletion of a selected record type. For example, an invoice-creation subscription represents a different invocation condition from an invoice-update or invoice-deletion subscription. The script file does not select the event; the SDF definition does.

Before deployment, review two requirements in the definition:

1. It references the intended Event Subscriber script file.
2. It contains at least one subscription criterion.

A missing criterion omits the required subscription. A reference to the wrong script file connects the selected event to unintended logic.

Deploy both artifacts in order

Create the behavior first, connect it to events second, then deploy both artifacts from the same SuiteCloud project. The definition references the script file, so use this sequence:

1. Create the Event Subscriber script file.
2. Create an Event Subscriber definition that references that file.
3. Add one or more subscription criteria to the definition.
4. Add both files to a SuiteCloud project.
5. Deploy the project to the target account.

A useful review sentence is: “When this selected record event occurs, invoke this script and perform this follow-up action.” The selected event belongs in the criteria, the SDF definition resolves the script-file reference, and handle(options) contains the action.

For deployment-tool troubleshooting outside the Event Subscriber contract, see the NetSuite custom tool error messages guide.

Deployment checklist and verification

Use this checklist before deployment:

• The follow-up work can run after the originating operation is complete.
• The script file uses SuiteScript 2.1.
• The script file declares @NScriptType EventSubscriber.
• The script file defines handle(options).
• The Event Subscriber SDF object definition references the intended script file.
• The definition contains one or more subscription criteria.
• The criteria identify the intended supported record event and selected record type.
• Both files are included in the same SuiteCloud project.
• The project is deployed to the target account.

After deployment, perform a supported record operation that matches the configured criterion. For an invoice-creation notification example, create an invoice and observe whether the intended notification follow-up occurs after the invoice creation operation completes. This confirms both parts of the implementation: handle(options) performs the intended action, and the SDF definition supplies the subscription that invokes it.

For general debugging context, see the SuiteScript Debugger guide for SuiteScript 1.0, 2.0, and 2.1. Keep Event Subscriber verification focused on the script-file reference, the selected record type, the selected event, and the observed follow-up result.

FAQ

What files are required for an Event Subscriber script?

You need a SuiteScript 2.1 script file that declares @NScriptType EventSubscriber and defines handle(options), plus an Event Subscriber SDF object definition that references the script file and includes one or more subscription criteria.

How do subscription criteria control execution?

They identify the supported record events that invoke the script, such as creation, update, or deletion of a selected record type. The definition must contain at least one criterion and reference the intended script file.

What is the deployment sequence?

Create the script file, create the definition that references it, add one or more criteria, add both files to the same SuiteCloud project, and deploy the project to the target account.

When should I choose an Event Subscriber instead of a User Event script?

Choose an Event Subscriber when follow-up work can run asynchronously after the originating operation completes. Choose a User Event script when the work must occur during record processing.