NetSuite Generic Set RESTlet – Complete Integration Spec (v1.1)

Executive Summary

This document describes the NetSuite RESTlet NSTS_SA_RL_Setter used as a generic inbound interface for creating, updating, and transforming NetSuite records, with a concrete implementation focused on Sales Orders for UTA Standard Contract Data Import.

It is intended as a consumable interface spec for new applications that must push contract, show, and commission data into NetSuite without changing the RESTlet code.

1. RESTlet Overview

1.1 Purpose

NSTS_SA_RL_Setter is a SuiteScript 2.x RESTlet that lets external systems:

Create and update NetSuite records via JSON;
Transform one record type into another (e.g., Sales Order → Invoice);
Set header fields, sublists, and subrecords dynamically based on the JSON payload.

In your use case, it is specifically used to:

Create and update Sales Orders representing UTA Standard Contracts;
Load custom contract header fields;
Populate the item sublist with GAAP commission items;
Populate custom sublists for agent splits and show/event details.

Because the RESTlet is generic, you do not need to modify the script when:

new custom fields are added to the Sales Order;
new shows are added to the contract;
agent commission splits change.

You only need to update the JSON payload coming from your external system.

1.2 Key Capabilities

Create new Sales Orders (UTA contracts).
Update existing Sales Orders by internalid or externalid.
Transform records using transformRecordType + transformId / transformTranId.
Populate:
- Standard item sublist;
- Custom record sublists:
  - recmachcustrecord_uta_agentsplit_so (Agent Split);
  - recmachcustrecord_uta_sales_order_id (Show/Event Details).
Support subrecords:
- addressbook, inventorydetail, landedcost (update mode).
Optionally log each inbound JSON request as a file in the File Cabinet.
Optionally trigger an additional script after processing.

1.3 Script Definition

@NApiVersion: 2.x
@NScriptType: Restlet
Entry point: EndPoint.post = handlePost

Dependencies:

N/record
N/search
N/runtime
N/error
N/format
../library/NSTS_SA_Lib_Main (file storage etc.)
../library/NSTS_SA_Lib_Utils (script runner)
../library/NSTS_SA_Lib_Constants (error codes)

A local utility object NSUtil provides isEmpty, inArray, and numeric parsing helpers.

2. How External Systems Call the RESTlet

2.1 Authentication

You can use:

Token‑Based Authentication (TBA) – recommended for production;
NLAuth – for legacy/testing only.

2.1.1 Token‑based Authentication example

http

POST /app/site/hosting/restlet.nl?script=customscript_nsts_sa_set_restlet&deploy=customdeploy_nsts_sa_set_restlet HTTP/1.1
Host: <ACCOUNT_ID>.restlets.api.netsuite.com
Content-Type: application/json
Authorization: OAuth realm="<ACCOUNT_ID>",
    oauth_consumer_key="<CONSUMER_KEY>",
    oauth_token="<TOKEN_ID>",
    oauth_signature_method="HMAC-SHA256",
    oauth_timestamp="<TIMESTAMP>",
    oauth_nonce="<NONCE>",
    oauth_version="1.0",
    oauth_signature="<SIGNATURE>"

2.1.2 NLAuth example

http

Authorization: NLAuth nlauth_account=<ACCOUNT_ID>,
    nlauth_email=<USER_EMAIL>,
    nlauth_signature=<USER_PASSWORD>,
    nlauth_role=<ROLE_ID>

2.2 Endpoint URL

text

https://<ACCOUNT_ID>.restlets.api.netsuite.com/app/site/hosting/restlet.nl
  ?script=customscript_nsts_sa_set_restlet
  &deploy=customdeploy_nsts_sa_set_restlet

script and deploy must match the IDs on Customization > Scripting > Script Deployments.

3. Request Format and High‑Level Behavior

3.1 HTTP Request

Method: POST
Content‑Type: application/json
Body: JSON array of one or more request objects.

3.2 High‑Level Flow in `handlePost`

For each request object in the array:

Validate request array – if empty/invalid, return a general script error.
Determine record type:
- recordType / recordtype / type (case‑insensitive).
Determine mode via Helper.getRecordObj:
- Transform: if transformRecordType present;
- Update: if matching externalid or internalid found;
- Create: otherwise.
Apply header fields:
- First, priority fields: customform, entity, subsidiary, externalid;
- Then all other body fields (excluding reserved keys).
Apply externalid (if present) as a separate step.
Apply sublists:
- item;
- recmachcustrecord_uta_agentsplit_so;
- recmachcustrecord_uta_sales_order_id;
- plus any other sublists you include.
Apply subrecords (e.g. addressbook) – only in update mode.
Attempt to save:
- If any field/sublist/subrecord processing produced errors, record is not saved, and all errors are returned.
- If no errors, record.save({ enableSourcing: true, ignoreMandatoryFields: true }) is called.
Optionally run a “post‑script” if configured via parameters.
Return the aggregated response array.

4. Mode Resolution: Create/Update/Transform

Helper.getRecordObj determines how each payload will be processed.

4.1 Transform Mode

If transformRecordType is present:

Optional transformTranId:
- The script searches for the source record by tranid.
If transformId is available (either from payload or search), then:

NS_Record.transform({
  fromType: option.transformRecordType,
  fromId:   option.transformId,
  toType:   option.recordType,
  isDynamic: true
});

Returns { mode: 'transform', record: <transformedRecord> }.

Typical use: transform a Sales Order to an Invoice, Item Fulfillment, etc.

4.2 Update via `externalid`

If transformRecordType is not present and externalid is present:

A search runs for recordType with filter ['externalid', 'is', externalid].
If found:
- NS_Record.load({ type: recordType, id: internalid, isDynamic: true });
- mode = update.
If not found:
- create new record (mode = create) and later set externalid.

4.3 Update via `internalid`

If internalid is present:

The script calls NS_Record.load({ type, id: internalid, isDynamic: true }).
mode = update.

4.4 Create (no ids)

If neither internalid nor externalid nor any transform fields are provided:

NS_Record.create({ type: recordType, isDynamic: true }).
mode = create.

5. Field Value Handling & Types

5.1 Input Conventions

Any field can be passed as:

Primitive (for simple cases)

json

"custbody_uta_contract_type": "Versus"

Structured object (recommended)

json

"custbody_uta_contract_type": { "text": "Versus" }
"subsidiary": { "value": "2" }
"trandate": { "value": "2/5/2026", "type": "date" }

The helper processField(option):

Extracts rawValue from option.value (or value / text inside it);
Normalizes based on option.type:
- date, datetime, datetimetz, timeofday;
- checkbox;
- currency, decimal, integer;
- default: text.

Then it decides between:

setFieldValue (by internal value), or
setFieldText (by display text).

5.2 Date/Time Fields

Helper.formatDate uses N/format to parse/format date/time fields:

type: 'date' → NS_Format.Type.DATE.
type: 'timeofday' → NS_Format.Type.TIMEOFDAY.
type: 'datetimetz' / type: 'datetime':
- Splits into date and time components;
- Parses and recombines into a single formatted string.

5.3 Checkbox Fields

Accepted “true” values: 'T', 't', 'true', 'True', 'TRUE', true.
Everything else is false.

5.4 Validation Logic

After setting any field, the script immediately reads it back:

For value fields:
- getValue or getCurrentSublistValue.
For text fields:
- getText or getCurrentSublistText.

If setValue != getValue, it throws "Field not properly set" and collects an error for that field.

6. Priority Fields and Reserved Keys

The script uses:

ARR_PRIORITY_FIELDS = ['customform', 'entity', 'subsidiary', 'externalid'];

These are applied before other body fields so that:

the correct form is used,
the correct entity/subsidiary is set,
externalid is available early.

The following keys are reserved and never treated as simple header fields:

internalid
externalid
recordtype
transformid
transformtranid
transformrecordtype
subrecord
sublist

7. UTA Contract – Sales Order Header Field Mapping

This section summarizes the main body fields present in your current UTA contract JSON payload.

7.1 Record Context

Record Type: salesorder
Purpose: UTA Standard Contract Data Import.
Key Identifiers:
- tranid.value – UTA contract number (e.g., "1339211").
- externalId.value – used by the RESTlet for upsert behavior.

7.2 Body Fields Table

Field ID	Example JSON	Data Type	Purpose
`customform`	`{"text":"UTA Standard Contract"}`	text	Use the UTA contract form.
`entity`	`{"text":"defaultartist"}`	text	Artist/customer entity.
`trandate`	`{"value":"2/5/2026","type":"date"}`	date	Contract date.
`subsidiary`	`{"value":"2"}`	select	Subsidiary for the contract.
`class`	`{"value":"2"}`	select	Class for reporting.
`department`	`{"value":"111"}`	select	Department.
`location`	`{"value":"1"}`	select	Location.
`currency`	`{"text":"US Dollar"}`	text	Transaction currency.
`externalId`	`{"value":"1339211"}`	value	External contract ID; used to find/update existing Sales Orders.
`tranid`	`{"value":"1339211"}`	value	Transaction ID (matches external contract id).
`custbody_uta_contract_artist_id_ext`	`{"value":"ARTIST_166247"}`	text/value	External artist ID.
`custbody_uta_contract_artist_code`	`{"value":"10"}`	text/value	Artist code.
`custbody_uta_contract_promoter_name`	`{"text":"Mic Drop Comedy Club"}`	text	Promoter.
`custbody_uta_contract_type`	`{"text":"Versus"}`	text	Contract type.
`custbody_uta_contract_cross_noncross`	`{"text":"None"}`	text	Cross vs. non‑cross.
`custbody_uta_contract_status`	`{"text":"Contract Issued"}`	text	High‑level contract status.
`custbody_uta_contract_issue_date`	`{"value":"2/5/2026","type":"date"}`	date	Date contract was issued.
`custbody_uta_contract_show_from`	`{"value":"9/11/2026","type":"date"}`	date	First show date.
`custbody_uta_contract_show_date_to`	`{"value":"9/12/2026","type":"date"}`	date	Last show date.
`custbody_uta_contract_gb_nb`	`{"text":"GBOR"}`	text	Guarantee basis.
`custbody_uta_contract_comm_rate`	`{"value":"10.00","type":"percent"}`	percent	Contract commission rate.
`custbody_uta_contract_gbor_perc`	`{"value":"85.000","type":"percent"}`	percent	GBOR percentage.
`custbody_uta_total_contract_guarantee`	`{"value":"5000.00","type":"currency"}`	currency	Total guarantee across all shows.
`custbody_uta_contract_total_net_adj`	`{"value":"0.00","type":"currency"}`	currency	Net adjustments on contract.
`custbody_uta_total_contract_deposit`	`{"value":"5500.00","type":"currency"}`	currency	Total deposit (including travel buyout, etc.).
`custbody_uta_total_overage`	`{"value":"0.00","type":"currency"}`	currency	Contract‑level overage.
`custbody_uta_contract_reductions`	`{"value":"0.00","type":"currency"}`	currency	Reductions.
`custbody_uta_contract_artist_reduction`	`{"value":"0.00","type":"currency"}`	currency	Artist reductions.
`custbody_uta_contract_agency_reduction`	`{"value":"0.00","type":"currency"}`	currency	Agency reductions.
`custbody_uta_contract_versus_thld`	`{"value":"5500.00","type":"currency"}`	currency	Versus threshold.
`custbody_uta_contract_travel_buyout`	`{"value":"500.00","type":"currency"}`	currency	Travel buyout at contract level.
`custbody_uta_contract_production`	`{"value":"0.00","type":"currency"}`	currency	Production costs.
`custbody_uta_contract_sponsorship`	`{"value":"0.00","type":"currency"}`	currency	Sponsorship amounts.
`custbody_uta_contract_catering`	`{"value":"0.00","type":"currency"}`	currency	Catering.
`custbody_uta_contract_support`	`{"value":"0.00","type":"currency"}`	currency	Support.
`custbody_uta_contract_other_buyout`	`{"value":"0.00","type":"currency"}`	currency	Other buyouts.
`custbody_uta_contract_net_guarantee`	`{"value":"5000.00","type":"currency"}`	currency	Net guarantee.
`custbody_uta_contract_direct_funds_art`	`{"value":"0.00","type":"currency"}`	currency	Direct funds to artist.
`custbody_uta_vat_to_artist`	`{"value":"0.00","type":"currency"}`	currency	VAT paid to artist.
`custbody_uta_contract_other_fees`	`{"value":"0.00","type":"currency"}`	currency	Other contract‑level fees.
`custbody_uta_contract_withholding_tax`	`{"value":"0.00","type":"currency"}`	currency	Withholding tax.
`custbody_uta_contract_inward_bank_char`	`{"value":"0.00","type":"currency"}`	currency	Inward bank charges.
`custbody_uta_others_memo`	`{"text":""}`	text	Free‑form memo.
`custbody_uta_withheld_memo`	`{"text":""}`	text	Withholding memo.
`custbody_uta_contract_inward_memo`	`{"text":""}`	text	Inward bank charges memo.

Memo‑style fields for hotel, train, car, etc. exist in the earlier sample; your spec can list them similarly if needed.

8. Sublists

8.1 Item Sublist (`item`)

Represents line items for GAAP commission on the Sales Order.

In your latest sample:

json

{
  "name": "item",
  "lines": [
    {
      "linenumber": "1",
      "fields": [
        {"field":"item","text":"Commission (GAAP)"},
        {"field":"custcol_uta_init_show","text":"555654"},
        {"field":"quantity","value":"1250.00","type":"decimal"},
        {"field":"rate","value":"0.1","type":"decimal"}
      ]
    },
    ...
  ]
}

Line fields:

Field ID	Sample Value	Data Type	Purpose
`item`	`"Commission (GAAP)"` (text)	select (by text)	Commission item.
`custcol_uta_init_show`	`"555654"`	text	Show identifier used to tie to custom show record.
`quantity`	`"1250.00"`	decimal	Commission base amount for the show.
`rate`	`"0.1"`	decimal	Commission rate (10%).

Line numbers 1, 2, 3, 4 correspond to each show; the script uses linenumber - 1 as the line index internally.

8.2 Agent Split Sublist (`recmachcustrecord_uta_agentsplit_so`)

A custom record sublist attached to the Sales Order representing agent commission splits.

Sample:

json

{
  "name": "recmachcustrecord_uta_agentsplit_so",
  "lines": [
    {
      "linenumber": "1",
      "fields": [
        {"field":"custrecord_uta_agentsplit_agentid","text":"AGENT_4767"},
        {"field":"custrecord_uta_agentsplit_type","text":"Booking Agent"},
        {"field":"custrecord_uta_agentsplit_perc","value":"50.00000000","type":"percent"}
      ]
    },
    {
      "linenumber": "2",
      "fields": [
        {"field":"custrecord_uta_agentsplit_agentid","text":"AGENT_1487"},
        {"field":"custrecord_uta_agentsplit_type","text":"Responsible Agent"},
        {"field":"custrecord_uta_agentsplit_perc","value":"25.00000000","type":"percent"}
      ]
    },
    ...
  ]
}

Fields:

Field ID	Sample Value	Data Type	Notes
`custrecord_uta_agentsplit_agentid`	`AGENT_4767`	text	Agent ID (by text).
`custrecord_uta_agentsplit_type`	`Booking Agent` / `Responsible Agent`	text	Role.
`custrecord_uta_agentsplit_perc`	`"50.00000000"`	percent	Commission split percentage.

Each line corresponds to one agent’s share of the commission.

8.3 Show/Event Details Sublist (`recmachcustrecord_uta_sales_order_id`)

A custom record sublist that models per‑show financials and metadata for the contract.

Example from your latest JSON:

json

{
  "name": "recmachcustrecord_uta_sales_order_id",
  "lines": [
    {
      "linenumber": "1",
      "fields": [
        {"field":"externalId","value":"555654"},
        {"field":"name","value":"555654"},
        {"field":"custrecord_uta_show_id","value":"555654"},
        {"field":"custrecord_uta_show_guarantee","value":"1250.00","type":"currency"},
        {"field":"custrecord_uta_show_deposit","value":"1375.00","type":"currency"},
        {"field":"custrecord_uta_show_travel_buyout","value":"125.00","type":"currency"},
        {"field":"custrecord_uta_show_overage","value":"0.00","type":"currency"},
        {"field":"custrecord_uta_show_reductions","value":"0.00","type":"currency"},
        {"field":"custrecord_uta_show_artist_reduction","value":"0.00","type":"currency"},
        {"field":"custrecord_uta_show_agency_reduction","value":"0.00","type":"currency"},
        {"field":"custrecord_uta_show_expected_funds","value":"1375.00","type":"currency"},
        {"field":"custrecord_uta_contract_id","value":"1339211"},
        {"field":"custrecord_uta_show_date","value":"9/11/2026","type":"date"},
        {"field":"custrecord_uta_show_time","text":"7:00pm"},
        {"field":"custrecord_uta_show_venue","value":"Mic Drop Comedy Club"},
        {"field":"custrecord_uta_show_event_id","value":"393995"},
        {"field":"custrecord_uta_show_final_entered","value":"F","type":"checkbox"},
        {"field":"custrecord_uta_show_approve_pay","value":"F","type":"checkbox"},
        {"field":"custrecord_uta_show_uta_settled","value":"F","type":"checkbox"},
        {"field":"custrecord_uta_show_direct_paid_artist","value":"0.00","type":"currency"},
        {"field":"custrecord_uta_show_post_adjustment","value":"0.00","type":"currency"},
        {"field":"custrecord_uta_show_status","text":"Confirmed"},
        {"field":"custrecord_uta_show_city","value":"Plano"},
        {"field":"custrecord_uta_show_zip","value":"75024"},
        {"field":"custrecord_uta_show_state","value":"TX"},
        {"field":"custrecord_uta_show_country","value":"United States"},
        {"field":"custrecord_uta_show_rate","value":"10.00","type":"percent"},
        {"field":"custrecord_uta_show_net_guarantee","value":"1250.00","type":"currency"},
        {"field":"custrecord_uta_show_other_fees","value":"0.00","type":"currency"},
        {"field":"custrecord_uta_show_bank_charges","value":"0.00","type":"currency"},
        {"field":"custrecord_uta_show_withholding_tax","value":"0.00","type":"currency"},
        {"field":"custrecord_uta_show_vat_on_artist_fee","value":"0.00","type":"currency"}
      ]
    },
    ...
  ]
}

Key fields (per show line):

Field ID	Sample Value	Data Type	Purpose
`externalId`	`555654`	value	Unique show ID (external).
`name`	`555654`	value	Name (often same as show ID).
`custrecord_uta_show_id`	`555654`	value	Show ID.
`custrecord_uta_contract_id`	`1339211`	value	Link back to contract (Sales Order) by external ID.
`custrecord_uta_show_event_id`	`393995`	value	External event ID.
`custrecord_uta_show_venue`	`Mic Drop Comedy Club`	text/value	Venue.
`custrecord_uta_show_city`	`Plano`	text/value	City.
`custrecord_uta_show_state`	`TX`	text/value	State.
`custrecord_uta_show_zip`	`75024`	text/value	ZIP code.
`custrecord_uta_show_country`	`United States`	text/value	Country.
`custrecord_uta_show_date`	`{"value":"9/11/2026","type":"date"}`	date	Show date.
`custrecord_uta_show_time`	`"7:00pm"`	text	Show time.
`custrecord_uta_show_rate`	`{"value":"10.00","type":"percent"}`	percent	Commission rate.
`custrecord_uta_show_guarantee`	`{"value":"1250.00","type":"currency"}`	currency	Guarantee per show.
`custrecord_uta_show_deposit`	`{"value":"1375.00","type":"currency"}`	currency	Deposit per show.
`custrecord_uta_show_net_guarantee`	`{"value":"1250.00","type":"currency"}`	currency	Net guarantee per show.
`custrecord_uta_show_expected_funds`	`{"value":"1375.00","type":"currency"}`	currency	Expected funds (guarantee + travel, etc.).
`custrecord_uta_show_overage`	`{"value":"0.00","type":"currency"}`	currency	Overage per show.
`custrecord_uta_show_reductions`	`{"value":"0.00","type":"currency"}`	currency	Total reductions per show.
`custrecord_uta_show_artist_reduction`	`{"value":"0.00","type":"currency"}`	currency	Artist reductions per show.
`custrecord_uta_show_agency_reduction`	`{"value":"0.00","type":"currency"}`	currency	Agency reductions per show.
`custrecord_uta_show_travel_buyout`	`{"value":"125.00","type":"currency"}`	currency	Travel buyout per show.
`custrecord_uta_show_direct_paid_artist`	`{"value":"0.00","type":"currency"}`	currency	Direct paid to artist per show.
`custrecord_uta_show_post_adjustment`	`{"value":"0.00","type":"currency"}`	currency	Post settlement adjustments.
`custrecord_uta_show_status`	`"Confirmed"`	text	Show status (e.g., Confirmed).
`custrecord_uta_show_final_entered`	`{"value":"F","type":"checkbox"}`	checkbox	Final settlement entered?
`custrecord_uta_show_approve_pay`	`{"value":"F","type":"checkbox"}`	checkbox	Approved to pay?
`custrecord_uta_show_uta_settled`	`{"value":"F","type":"checkbox"}`	checkbox	UTA settled?
`custrecord_uta_show_other_fees`	`{"value":"0.00","type":"currency"}`	currency	Other fees per show.
`custrecord_uta_show_bank_charges`	`{"value":"0.00","type":"currency"}`	currency	Bank charges.
`custrecord_uta_show_withholding_tax`	`{"value":"0.00","type":"currency"}`	currency	Withholding tax.
`custrecord_uta_show_vat_on_artist_fee`	`{"value":"0.00","type":"currency"}`	currency	VAT on artist fee.

This sublist gives you a normalized per‑show ledger that ties back to:

contract header amounts, and
custcol_uta_init_show on each item sublist line.

9. Subrecords

The script supports subrecord updates (only in update mode):

addressbook – via Helper.processSubrecordAddressBook:
- Selects or inserts addressbook lines;
- Uses a nested subrecord addressbookaddress to set address fields (e.g., country, addr1, city, state, zip).
inventorydetail – placeholder function processSubrecordInventoryDetail.
landedcost – placeholder processSubrecordLandedCost.

Subrecords are passed via a subRecord key in the request object, similar to:

json

"subRecord": [
  {
    "name": "addressbook",
    "lines": [
      {
        "line": 1,
        "defaultbilling": true,
        "defaultshipping": false,
        "fields": [
          {"field": "country", "value": "US", "type": "select"},
          {"field": "addr1", "value": "123 Main St"},
          ...
        ]
      }
    ]
  }
]

10. Response Format

The RESTlet returns a JSON array with one element per request object.

10.1 Success

json

[
  {
    "mode": "create",
    "id": "12345"
  },
  {
    "mode": "update",
    "id": "67890"
  }
]

10.2 Partial Error (record fields error, not saved)

If any field/sublist/subrecord fails validation, the record is not saved and the ERROR array describes why:

json

[
  {
    "mode": "create",
    "ERROR": [
      "ERROR on [quantity] Field not properly set",
      "UNABLE to save, errors encountered"
    ]
  }
]

10.3 Critical Error (e.g., missing `recordType`)

json

[
  {
    "ERROR": {
      "CODE": "MISSING_REQUIRED_PARAMETER",
      "NAME": "Missing Required Parameter",
      "MESSAGE": "recordType is required"
    }
  }
]

11. Request Logging – Finding Stored JSON Files

The RESTlet optionally stores each inbound request as a JSON file in the File Cabinet.

11.1 Script Parameters Used

On the RESTlet deployment:

custscript_nsts_sa_set_storeq_folder → The internal ID of the File Cabinet folder where requests are saved.
custscript_nsts_sa_set_storeq_filename → Filename pattern (string template) for request files.

If custscript_nsts_sa_set_storeq_folder has a value, the script:

Builds fileOption.folderId from the parameter.
Sets fileOption.fileName to either:
- custscript_nsts_sa_set_storeq_filename, or
- a default: requestFile_set-restlet_${.now?string["yyyyMMdd-HH:mm:ss"]}.
Renders this filename using NSTSLibSuiteAdapter.renderContentStr(...).
Sets fileOption.content = JSON.stringify(context) (the entire request array).
Calls NSTSLibSuiteAdapter.storeToFile(fileOption) to write it.

11.2 How to Locate These Files in NetSuite

Go to Customization > Scripting > Script Deployments.
Locate the deployment for NSTS_SA_RL_Setter (or equivalent label).
Open the deployment record.
Scroll down to the Parameters section.
Note the value of custscript_nsts_sa_set_storeq_folder:
- This is a File Cabinet folder (often clickable).
Click that folder link (if available), or:
- Go to Documents > Files > File Cabinet;
- Navigate to the folder ID / name shown in the parameter.
Look for files matching the naming pattern (e.g., requestFile_set-restlet_20260205-10:11:40.json).

Alternatively:

In File Cabinet, use the search box:
- Name contains requestFile_set-restlet;
- Filter by date created.

Each file will contain the original request JSON for auditing and test replay.

12. Optional Post‑Processing Script

The RESTlet can trigger another script after successful processing of the request array.

Deployment parameters:

custscript_nsts_sa_set_runafter_scriptid – internal script ID of a server script (e.g., scheduled or map/reduce).
custscript_nsts_sa_set_runafter_deployid – deployment ID of that script.
custscript_nsts_sa_set_runafter_paramreq – name of the script parameter that should receive the original request data.

If custscript_nsts_sa_set_runafter_scriptid is set:

The RESTlet builds a scriptOption object:
- .scriptId from parameter;
- .deploymentId if provided;
- .params[<param name>] = objRequests if param name is provided.
Calls NSTSUtil.runServerScript(scriptOption) to trigger it.

This allows you to:

Push the contract into NetSuite via RESTlet;
Kick off downstream jobs (e.g., rev rec schedule creation, reporting, or asynchronous processing).

13. Best Practices for Your New Finance Application

Use externalId for idempotent upsert semantics for contracts and show lines.
Treat the Sales Order as your header contract; treat:
- item lines as revenue/commission drivers;
- recmachcustrecord_uta_agentsplit_so as commission split meta;
- recmachcustrecord_uta_sales_order_id as per‑show detail.
Build a library of JSON templates for:
- Single‑show contracts;
- Multi‑show contracts;
- Different commission structures.
Use the request logging folder as your “golden source” for samples and debugging.
Keep each batch’s array size manageable (e.g., 10–25 contracts) to reduce governance pressure.

14. Example: Full UTA Contract JSON (abridged)

Below is your latest real‑world sample, formatted:

json

[
  {
    "recordType": "salesorder",
    "customform": {"text":"UTA Standard Contract"},
    "entity": {"text":"defaultartist"},
    "custbody_uta_contract_artist_id_ext": {"value":"ARTIST_166247"},
    "currency": {"text":"US Dollar"},
    "trandate": {"value":"2/5/2026","type":"date"},
    "custbody_uta_total_contract_guarantee": {"value":"5000.00","type":"currency"},
    "custbody_uta_contract_total_net_adj": {"value":"0.00","type":"currency"},
    "custbody_uta_total_contract_deposit": {"value":"5500.00","type":"currency"},
    "custbody_uta_total_overage": {"value":"0.00","type":"currency"},
    "custbody_uta_contract_reductions": {"value":"0.00","type":"currency"},
    "custbody_uta_contract_artist_reduction": {"value":"0.00","type":"currency"},
    "custbody_uta_contract_agency_reduction": {"value":"0.00","type":"currency"},
    "custbody_uta_contract_type": {"text":"Versus"},
    "custbody_uta_contract_cross_noncross": {"text":"None"},
    "custbody_uta_contract_status": {"text":"Contract Issued"},
    "subsidiary": {"value":"2"},
    "class": {"value":"2"},
    "department": {"value":"111"},
    "location": {"value":"1"},
    "custbody_uta_contract_artist_code": {"value":"10"},
    "custbody_uta_contract_comm_rate": {"value":"10.00","type":"percent"},
    "custbody_uta_contract_gb_nb": {"text":"GBOR"},
    "custbody_uta_contract_gbor_perc": {"value":"85.000","type":"percent"},
    "custbody_uta_contract_versus_thld": {"value":"5500.00","type":"currency"},
    "custbody_uta_contract_issue_date": {"value":"2/5/2026","type":"date"},
    "custbody_uta_contract_travel_buyout": {"value":"500.00","type":"currency"},
    "custbody_uta_contract_production": {"value":"0.00","type":"currency"},
    "custbody_uta_contract_sponsorship": {"value":"0.00","type":"currency"},
    "custbody_uta_contract_catering": {"value":"0.00","type":"currency"},
    "custbody_uta_contract_support": {"value":"0.00","type":"currency"},
    "custbody_uta_contract_other_buyout": {"value":"0.00","type":"currency"},
    "custbody_uta_contract_net_guarantee": {"value":"5000.00","type":"currency"},
    "custbody_uta_contract_direct_funds_art": {"value":"0.00","type":"currency"},
    "custbody_uta_vat_to_artist": {"value":"0.00","type":"currency"},
    "custbody_uta_contract_other_fees": {"value":"0.00","type":"currency"},
    "custbody_uta_others_memo": {"text":""},
    "custbody_uta_contract_withholding_tax": {"value":"0.00","type":"currency"},
    "custbody_uta_withheld_memo": {"text":""},
    "custbody_uta_contract_inward_bank_char": {"value":"0.00","type":"currency"},
    "custbody_uta_contract_inward_memo": {"text":""},
    "tranid": {"value":"1339211"},
    "custbody_uta_contract_promoter_name": {"text":"Mic Drop Comedy Club"},
    "custbody_uta_contract_show_from": {"value":"9/11/2026","type":"date"},
    "custbody_uta_contract_show_date_to": {"value":"9/12/2026","type":"date"},
    "externalId": {"value":"1339211"},

    "sublist": [
      {
        "name": "item",
        "lines": [
          {
            "linenumber":"1",
            "fields":[
              {"field":"item","text":"Commission (GAAP)"},
              {"field":"custcol_uta_init_show","text":"555654"},
              {"field":"quantity","value":"1250.00","type":"decimal"},
              {"field":"rate","value":"0.1","type":"decimal"}
            ]
          },
          {
            "linenumber":"2",
            "fields":[ ... ]
          },
          {
            "linenumber":"3",
            "fields":[ ... ]
          },
          {
            "linenumber":"4",
            "fields":[ ... ]
          }
        ]
      },
      {
        "name": "recmachcustrecord_uta_agentsplit_so",
        "lines": [ ... ]
      },
      {
        "name": "recmachcustrecord_uta_sales_order_id",
        "lines": [ ... ]
      }
    ]
  }
]

Sample Deals

Touring Deal

Endorsement Deal

Sports Endo Deal

NetSuite Generic Set RESTlet – Complete Integration Spec (v1.1) ​

Executive Summary ​

1. RESTlet Overview ​

1.1 Purpose ​

1.2 Key Capabilities ​

1.3 Script Definition ​

2. How External Systems Call the RESTlet ​

2.1 Authentication ​

2.1.1 Token‑based Authentication example ​

2.1.2 NLAuth example ​

2.2 Endpoint URL ​

3. Request Format and High‑Level Behavior ​

3.1 HTTP Request ​

3.2 High‑Level Flow in handlePost ​

4. Mode Resolution: Create/Update/Transform ​

4.1 Transform Mode ​

4.2 Update via externalid ​

4.3 Update via internalid ​

4.4 Create (no ids) ​

5. Field Value Handling & Types ​

5.1 Input Conventions ​

5.2 Date/Time Fields ​

5.3 Checkbox Fields ​

5.4 Validation Logic ​

6. Priority Fields and Reserved Keys ​

7. UTA Contract – Sales Order Header Field Mapping ​

7.1 Record Context ​

7.2 Body Fields Table ​

8. Sublists ​

8.1 Item Sublist (item) ​

8.2 Agent Split Sublist (recmachcustrecord_uta_agentsplit_so) ​

8.3 Show/Event Details Sublist (recmachcustrecord_uta_sales_order_id) ​

9. Subrecords ​

10. Response Format ​

10.1 Success ​

10.2 Partial Error (record fields error, not saved) ​

10.3 Critical Error (e.g., missing recordType) ​

11. Request Logging – Finding Stored JSON Files ​

11.1 Script Parameters Used ​

11.2 How to Locate These Files in NetSuite ​

12. Optional Post‑Processing Script ​

13. Best Practices for Your New Finance Application ​

14. Example: Full UTA Contract JSON (abridged) ​

NetSuite Generic Set RESTlet – Complete Integration Spec (v1.1)

Executive Summary

1. RESTlet Overview

1.1 Purpose

1.2 Key Capabilities

1.3 Script Definition

2. How External Systems Call the RESTlet

2.1 Authentication

2.1.1 Token‑based Authentication example

2.1.2 NLAuth example

2.2 Endpoint URL

3. Request Format and High‑Level Behavior

3.1 HTTP Request

3.2 High‑Level Flow in `handlePost`

4. Mode Resolution: Create/Update/Transform

4.1 Transform Mode

4.2 Update via `externalid`

4.3 Update via `internalid`

4.4 Create (no ids)

5. Field Value Handling & Types

5.1 Input Conventions

5.2 Date/Time Fields

5.3 Checkbox Fields

5.4 Validation Logic

6. Priority Fields and Reserved Keys

7. UTA Contract – Sales Order Header Field Mapping

7.1 Record Context

7.2 Body Fields Table

8. Sublists

8.1 Item Sublist (`item`)

8.2 Agent Split Sublist (`recmachcustrecord_uta_agentsplit_so`)

8.3 Show/Event Details Sublist (`recmachcustrecord_uta_sales_order_id`)

9. Subrecords

10. Response Format

10.1 Success

10.2 Partial Error (record fields error, not saved)

10.3 Critical Error (e.g., missing `recordType`)

11. Request Logging – Finding Stored JSON Files

11.1 Script Parameters Used

11.2 How to Locate These Files in NetSuite

12. Optional Post‑Processing Script

13. Best Practices for Your New Finance Application

14. Example: Full UTA Contract JSON (abridged)