RESTlet actions

One endpoint handles every sync, dispatched on the payload's action. Every packaged sync pushes with POST. PUT works as an alias, and eight read-only actions also answer GET. This is the wire-level catalog. For the pipeline mechanics, see Inside the RESTlet.

Calling the endpoint

The endpoint is the Continuous Control (RESTlet) script record, the one entry point for every action below. Salesforce's revenue engine also calls the Update POBs and Update Revenue Plans Suitelets directly, outside this dispatch. See The engine Suitelets for those two, and Inside the RESTlet for how a call reaches an action here.

POST https://<account>.restlets.api.netsuite.com/app/site/hosting/restlet.nl
     ?script=customscript_cc_control_rl&deploy=customdeploy_cc_control_rl
Authorization: OAuth 1.0a (HMAC-SHA256; query params included in the signature)
Content-Type: application/json

{ "action": "…", … }

PUT  same URL, same body                // alias of POST, for endpoints that require it
GET  same URL &action=ping             // read-only actions only: ping, setupinfo,
                                        // installcheck, listrecordtypes, refdata, itemlist, describe,
                                        // settingsoptions

Each call can be pointed at a different URL, method, and action. The values above are the defaults every packaged call uses. The install registers GET and PUT on the script record along with POST.

Every push call's body carries orgBaseUrl and orgId. These are the Salesforce org's My Domain host and its 18-character org id. Together they let NetSuite build "Open in NetSuite" deep links and stamp the Source Org field. See Anatomy of the payload for the full envelope shape.

Action reference

Any other action value returns {ok:false, errors:["unknown action: …"]}.

Files, folders, and extensions

The files action attaches a Salesforce-generated document to a NetSuite record. Everything lands under one shared folder:

• Folder. The top-level "Continuous Documents" folder, created once, with its id kept on Continuous Revenue Settings. A payload's optional folderName creates or reuses a subfolder of it: one plain name, no path separators. A name outside that shape is refused before anything is created or deleted.
• Extension. Only document and image extensions are accepted: pdf, doc, docx, xls, xlsx, ppt, pptx, png, jpg, jpeg, gif, bmp, tif, tiff, zip, csv, txt, rtf, odt, and ods. A name with none of these is saved as a plain file that NetSuite never runs. A name with no extension at all works the same way, so "DOC-1 - Kingsbridge Digital Ltd." still lands. A script or markup extension, like .js, .html, or .svg, is refused.
• Target. The record type must be one Continuous syncs, named with a numeric NetSuite internal id. That's an invoice, credit memo, customer payment, customer refund, sales order, estimate, cash sale, return authorization, customer, or the RC Contract or RC Order custom record.

Every check runs before the same-name file it would replace is deleted, so a refused file never removes an existing one. A same-name file that passes every check replaces it, since a regenerated document should refresh in place.

Governance and dispatcher errors

NetSuite meters script work per request. Every write action checks the usage left before each row, so a large request stops cleanly instead of failing outright. A call that resumes by document, rather than by section, reports a document synced only once everything under it landed. A single-document call that can't finish fails with a message telling you to sync it again.

An error the RESTlet can't otherwise handle answers {ok:false, version, errors:[…]} instead of NetSuite's own error page. The message names the action, and tells you to check the script log and run it again.

Relaying to another RESTlet

When an admin points a call at another RESTlet in this account, a script your team or a vendor already owns, Salesforce doesn't call it directly. It posts to the Continuous endpoint as usual, with action:'relay' and the target from the endpoint row. NetSuite forwards the payload from the inside:

{ "action": "relay",
  "target": { "scriptId": "customscript_partner_thing",
              "deployId": "customdeploy_partner_thing",
              "action":   "ingest" },        // optional: what the TARGET calls it
  "callKey": "…", "customNodes": [ … ]       // or "body": { … } to send exactly that
}

Going through us means the forward happens inside NetSuite, under the same role. There's no second credential to store, no second Remote Site entry, no OAuth signature for someone else's endpoint, and no secret ever leaves the account. Both target ids are required, since NetSuite's own RESTlet-to-RESTlet call needs the deployment as well as the script.

The target's own deployment audience must include this connection's role. A relay carries no second credential, so it runs as whichever role the connection's token uses. If the target RESTlet's deployment is scoped to a different set of roles, NetSuite refuses the in-account call itself. It comes back as an HTTP error under relay.status, not a Continuous-worded refusal. Check the target's deployment audience before pointing a call at it.

Two more limits are checked before anything is sent, both from ns-v3.2.0 (audit N16):

• The relay allowlist. Relay Allowlist on Continuous Revenue Settings (script ids, one per line). Blank allows any RESTlet except this endpoint, as before. Set, only a listed script id is allowed, matched with or without the customscript_ prefix; a numeric target matches only a numeric entry. A settings record that exists but can't be read refuses the relay rather than treating the list as blank.
• Loops. Every hop appends its own script id to relayChain in the forwarded body. NetSuite refuses to send when the chain already names this endpoint, meaning the call already came back around. It also refuses a target already in the chain, or a chain that would pass three relays.

What goes over the wire is your payload minus the two routing keys that are ours. The target key is removed. The action key becomes target.action, or is dropped entirely when the target doesn't use one, since relay is our word, not theirs. Everything else rides verbatim. Send body instead when the call's own shape and the target's differ. Then that object is sent as-is.

What comes back is the target's answer, wrapped and never rewritten. relay.sent says whether the request ever left NetSuite. When it's true, relay.status is the HTTP status, and relay.body is its answer: parsed when it's JSON, raw text otherwise.

If the target speaks the same wire format Continuous does, its customIds, customIdsByNode, counts, ids, pobs, errors, notes, partial, and customNodesFrom are lifted to the top level. That's what lets Salesforce's writeback and continuation loops treat a relayed call the same way as a direct one.

Don't relay Order Line Sync. The relay doesn't lift its skipped, affectedContracts or continueFrom keys, so a relayed run loses its skipped-line warnings and can't resume.

If it speaks something else, nothing is lifted. ok follows the HTTP status, and a note says so. The run records "sent" rather than failing.

relay.body is capped at 65,536 characters. Without the cap, a chatty target could carry its answer twice: once whole, and once as the lifted keys. That could turn a working relay into an opaque "response too large" failure. The lift happens first, so the machine-readable half always survives. Past the cap, the body is replaced by a marker saying how big it was, and relay.truncated is set.

One leg per call. The relay never chunks a payload. It forwards what it was given, cursor and all, and passes the target's own partial and customNodesFrom back up. Governance sizing belongs to the two ends, not to the courier between them.

NetSuite refuses a relay before sending anything, for any of these reasons:

• The target is this endpoint itself. That's a loop, or a second and weaker door into an action you could name directly. NetSuite checks every id form it accepts, the script id string and the internal id the Scripts list shows, and names whichever half matched.
• The target is missing its script or deployment id.
• A numeric target can't be checked against our own ids, because the lookup failed. The message names whichever id was unverifiable, never the half that already answered.
• The chain already names this endpoint or the target, or the chain would pass three relays. The message names which.
• The target isn't on the Relay Allowlist, when one is set. The message names the script id and where to add it.
• The transport itself fails: the id doesn't exist, it's a Suitelet rather than a RESTlet, the connection's role isn't in the target's own deployment audience, or the call times out. Nothing was delivered, so NetSuite's own message rides in errors instead of being dressed up as a status.

Nothing answered means no status. Every refusal comes back ok:false, partial:false, relay.sent:false, and relay.status:null. It never fakes a 0, which downstream would read as "the target answered badly" when really it was never asked. Salesforce reports these as not sent, with NetSuite's reason, and fails the run. The same payload would be refused the same way again.

There's one other not-sent answer, and it means the opposite, told apart by partial. A leg NetSuite stopped for governance comes back ok:true, partial:true, with the same customNodesFrom cursor, and the run re-posts it.

The relay is a courier, not an adapter. It doesn't know or care what the target's payload means, and it doesn't translate. Vendor-specific adapters aren't built until a specific vendor needs one.

The write block

Every push action can carry record entries an admin configured, in customNodes[]. The book action carries them alongside the fixed order graph. The invoices, payments, refunds, items, and customer actions carry them alongside their own documents. The custom action is nothing but those entries. They all go through one engine and one record writer, so an entry means the same thing no matter which action carries it.

Any entry can add an optional write block saying how the record should be written. Every key is optional, and an entry without a write block uses the defaults. The full schema is annotated in Anatomy of the payload.

A sublist row can be a record. Alongside append, match, and replace, a sublist can be driven in subrecord mode. An entity's address book works this way. The row itself holds only a label and the two default flags. The address lives in a nested record hanging off one of its columns.

Two keys go with the mode. subrecordId names that column. It defaults to addressbookaddress on an addressbook, and is required on anything else, since guessing wrong would write the address into a plain column. The ensureDefaults key, on by default for an addressbook, settles the default billing and shipping flags across the record after the rows are written.

The rules, in short:

• Keyed by a native column. That's label for an address book, taken from the row's own key, never from its Salesforce id, since every address on one account shares that id.
• Routed by field id. A sublist column lands on the row. Everything else lands on the subrecord.
• Mirrors the payload. A key sent blank blanks that field. A key nobody sent is left alone. country is the one exception: it's written first, and never blanked, since an address with no country validates nothing.
• Never deletes. A row a NetSuite user added isn't even reported as unmatched.

Settling the flags is a whole-record pass, not a per-row one. The row the payload marks default is the only one that keeps that flag. A record left with only one address carries both flags. A lone existing row already carrying a flag gets adopted and relabeled instead of duplicated. That's what keeps a matched customer's existing NetSuite addresses from being copied.

Lookups resolve by external id, and only by external id. A lookups entry, and a nested row's keyRef, names a table and the external id of the record it wants. There's no by key: the writer doesn't read one, and Salesforce doesn't emit one, so a resolution mode isn't something a payload can select. A miss becomes a per-field error naming the value, and the record still writes.

Any action's payload can also carry requiresVersion, the package version the call needs. Salesforce stamps it from the activated configuration and from what the built payload turned out to need. NetSuite checks it first, ahead of the action. A payload asking for more than the installed package can do is refused with {ok:false, requiresVersion, errors:[…]}, and nothing is written.

Response envelope

Every write action shares this envelope:

Two informational arrays ride alongside. The notes[] array covers things worth knowing that aren't errors: a section skipped, a line NetSuite kept that the payload stopped sending, or the native Sales Order generator standing down. That last one reads native sales order skipped - Order targets salesorder when a Sales Order node booked the run. It reads native sales order skipped - Disable Native Sales Orders is checked in Continuous Revenue Settings when NetSuite refuses it instead. The skippedNodes[] array names each node the payload deliberately omitted.

Long-running writes can return partial:true with continueFrom. The Salesforce worker resumes automatically. See governance and resume.

A response that landed records for extension nodes carries two id maps instead of one. The customIds key is the flat Salesforce id to NetSuite internal id map. The customIdsByNode key files the same ids under the node that wrote them, as {nodeKey: {sfId: nsId}}. That's what keeps two nodes over the same Salesforce record unambiguous: each one writes back its own document's id, instead of both taking whichever landed last. Writebacks prefer the by-node map and fall back to the flat one. Both keys are absent when a run landed no extension records at all.