Worlds / Finance ops

NetSuite API

A local NetSuite account with subsidiaries, purchase orders, vendor bills, journal entries and accounting periods. Test the agent that moves POs through approval, matches bills and helps close the month.

Base path: /services/rest/record/v1
Auth: OAuth 2.0 bearer token, the world key
Endpoints: 17
Status: Active today

This reference previews the surface the NetSuite world serves in the closed beta. Paths mirror the public NetSuite API; the exact subset is confirmed when your workflow is scoped.

Connect

The run gives your agent these bindings. Keep your SDK; change only where it sends requests.

binding	meaning
`WORLDS_NETSUITE_URL`	This world's origin followed by `/services/rest/record/v1`
`WORLDS_API_KEY`	The world key, accepted wherever NetSuite expects a credential
`WORLDS_WORLD_ID`	The isolated world's identity

js · fetch

const base = process.env.WORLDS_NETSUITE_URL;
const headers = {
  Authorization: "Bearer " + process.env.WORLDS_API_KEY,
  "Content-Type": "application/json",
};

const res = await fetch(base + "/services/rest/record/v1/invoice/123", { headers });
const invoice = await res.json();

API reference

17 of 17

Customers

Customer records.

POST/services/rest/record/v1/customerCreate a customer
GET/services/rest/record/v1/customer/{id}Get a customer
PATCH/services/rest/record/v1/customer/{id}Update a customer
GET/services/rest/record/v1/customerList customers

Fields · 4

`id`	string	Internal id
`companyName`	string	Company name
`email`	string	Email
`balance`	number	Open balance

Invoices

Sales invoices.

POST/services/rest/record/v1/invoiceCreate an invoice
GET/services/rest/record/v1/invoice/{id}Get an invoice
PATCH/services/rest/record/v1/invoice/{id}Update an invoice
DELETE/services/rest/record/v1/invoice/{id}Delete an invoice

Fields · 5

`id`	string	Internal id
`tranId`	string	Invoice number
`entity`	object	Customer reference
`total`	number	Total
`amountRemaining`	number	Unpaid amount

Sales orders

Orders that fulfil into invoices.

POST/services/rest/record/v1/salesOrderCreate a sales order
GET/services/rest/record/v1/salesOrder/{id}Get a sales order
PATCH/services/rest/record/v1/salesOrder/{id}Update a sales order

Fields · 4

`id`	string	Internal id
`tranId`	string	Order number
`status`	string	Pending approval, billed and more
`item`	object	Line items

Vendor bills

Payables from vendors.

POST/services/rest/record/v1/vendorBillCreate a vendor bill
GET/services/rest/record/v1/vendorBill/{id}Get a vendor bill
POST/services/rest/record/v1/vendorPaymentPay a vendor bill

Fields · 4

`id`	string	Internal id
`entity`	object	Vendor reference
`total`	number	Total
`dueDate`	date	Due date

Journal entries

Manual ledger postings.

POST/services/rest/record/v1/journalEntryCreate a journal entry
GET/services/rest/record/v1/journalEntry/{id}Get a journal entry
GET/services/rest/record/v1/journalEntryList journal entries

Fields · 4

`id`	string	Internal id
`tranDate`	date	Posting date
`subsidiary`	object	Subsidiary
`line`	object	Debit and credit lines

Test workflow

Prepare. Select the NetSuite setup for your workflow and review its starting records, including customers, invoices, sales orders.
Connect. Configure your agent with this world's URL and key using the SDK example. Check that it reaches the intended API before running a test.
Define. Describe the task, expected final changes and records that must stay untouched. Keep expected outcomes separate from the agent's instructions.
Run and inspect. Use the dashboard or your workflow's generated CLI setup. Review final records and changes, then rerun from the same starting setup with the relevant failure conditions. Use Deployment and CI to automate the same workflow.

What to verify

PO-2210 approved
PO-2214 still pending, routed to the CFO
PO-2189 billed for the received quantity only
Accruals posted to October with a November reversal
No transaction posted to September

Test file

A task file names the jobs, the policy your agent is given and what the grader reads back from the world's final state. The agent never sees the expected outcomes.

yaml · worlds/tasks.yaml

# worlds/tasks.yaml · NetSuite
version: 2
connector: netsuite
seed: netsuite-starter
mode: isolated
policy: >
  Clear the PO approval queue. Approve anything under $50,000 and send larger
  ones to the CFO. Bill PO-2189 against what was received and book October
  accruals.
tasks:
  - id: approve-or-reject-purchase-orders-by-limit
    prompt: Approve or reject purchase orders by limit
  - id: match-a-vendor-bill-to-its-po-and-receipt
    prompt: Match a vendor bill to its PO and receipt
  - id: post-accrual-journals-before-period-close
    prompt: Post accrual journals before period close
expected:
  - PO-2210 approved
  - "PO-2214 still pending, routed to the CFO"
  - PO-2189 billed for the received quantity only
  - Accruals posted to October with a November reversal
  - No transaction posted to September
scenarios:
  - period-closed
  - concurrency
  - user-error

See Tasks and outcomes for every field, and Deployment and CI to run the file on every pull request.

Failure conditions

Each one fires before the handler, at the same step on every run.

condition	what the agent sees
`period-closed`	Posting a journal into September returns a closed period error
`concurrency`	Parallel REST calls are rejected past the account concurrency limit
`user-error`	A bill missing a required department returns USER_ERROR
`token-revoked`	The token based auth credential is revoked mid run

Starting data

Start each run from the same records and relationships. The overview below describes the NetSuite starter; use the setup supplied for your workflow when preparing your own snapshot.

Records	Starting setup
subsidiaries	US, UK and Canada with their own currencies
purchase orders	65 across Pending Supervisor Approval to Fully Billed
vendor bills	48 with 9 pending approval
journal entries	120 posted, 6 pending approval
accounting periods	Sep closed, Oct open

The record shapes below reuse this world's API field definitions. They show illustrative values and placeholders, not an importable seed. API responses and seed input can differ; include all required records and references in the accepted import format for your workflow.

Customers records

Customers

Customer records.

Field	Type	Meaning / relationship
`id`	string	Internal id
`companyName`	string	Company name
`email`	string	Email
`balance`	number	Open balance

json · illustrative record shape

{
  "id": "<Internal id>",
  "companyName": "<Company name>",
  "email": "person@example.test",
  "balance": 1
}

See customers operations

Invoices records

Invoices

Sales invoices.

Field	Type	Meaning / relationship
`id`	string	Internal id
`tranId`	string	Invoice number
`entity`	object	Customer reference
`total`	number	Total
`amountRemaining`	number	Unpaid amount

json · illustrative record shape

{
  "id": "<Internal id>",
  "tranId": "<Invoice number>",
  "entity": {},
  "total": 1,
  "amountRemaining": 1
}

See invoices operations

Sales orders records

Sales orders

Orders that fulfil into invoices.

Field	Type	Meaning / relationship
`id`	string	Internal id
`tranId`	string	Order number
`status`	string	Pending approval, billed and more
`item`	object	Line items

json · illustrative record shape

{
  "id": "<Internal id>",
  "tranId": "<Order number>",
  "status": "<Pending approval, billed and more>",
  "item": {}
}

See sales orders operations

Vendor bills records

Vendor bills

Payables from vendors.

Field	Type	Meaning / relationship
`id`	string	Internal id
`entity`	object	Vendor reference
`total`	number	Total
`dueDate`	date	Due date

json · illustrative record shape

{
  "id": "<Internal id>",
  "entity": {},
  "total": 1,
  "dueDate": "<Due date>"
}

See vendor bills operations

Journal entries records

Journal entries

Manual ledger postings.

Field	Type	Meaning / relationship
`id`	string	Internal id
`tranDate`	date	Posting date
`subsidiary`	object	Subsidiary
`line`	object	Debit and credit lines

json · illustrative record shape

{
  "id": "<Internal id>",
  "tranDate": "<Posting date>",
  "subsidiary": {},
  "line": {}
}

See journal entries operations

See the NetSuite world in the catalog