Worlds / Payments and billing

Bill.com API

A local Bill.com with vendors, bills, approval policies and scheduled ACH and check payments. Test the AP agent that codes bills, routes them for approval and schedules payments.

Base path: /v3
Auth: Session id and dev key headers, the world key
Endpoints: 20
Status: Active today

This reference previews the surface the Bill.com world serves in the closed beta. Paths mirror the public Bill.com 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_BILL_COM_URL`	This world's origin followed by `/v3`
`WORLDS_API_KEY`	The world key, accepted wherever Bill.com expects a credential
`WORLDS_WORLD_ID`	The isolated world's identity

js · fetch

const base = process.env.WORLDS_BILL_COM_URL;
const headers = {
  sessionId: process.env.WORLDS_API_KEY,
  devKey: "dev-key",
  "Content-Type": "application/json",
};

const res = await fetch(base + "/v3/bills?max=20", { headers });
const { results } = await res.json();

API reference

20 of 20

Bills

Vendor bills to approve and pay.

POST/v3/billsCreate a bill
GET/v3/bills/{id}Get a bill
PATCH/v3/bills/{id}Update a bill
GET/v3/billsList bills
POST/v3/bills/{id}/archiveArchive a bill

Fields · 6

`id`	string	Bill id
`vendorId`	string	Vendor id
`invoice`	object	Invoice number and date
`amount`	number	Bill total
`approvalStatus`	string	Approval state
`paymentStatus`	string	Unpaid, scheduled or paid

Vendors

Suppliers you pay.

POST/v3/vendorsCreate a vendor
GET/v3/vendors/{id}Get a vendor
PATCH/v3/vendors/{id}Update a vendor
GET/v3/vendorsList vendors

Fields · 4

`id`	string	Vendor id
`name`	string	Vendor name
`email`	string	Contact email
`paymentInformation`	object	Payment method details

Payments

Outgoing payments for bills.

POST/v3/paymentsPay a bill
GET/v3/payments/{id}Get a payment
POST/v3/payments/{id}/cancelCancel a scheduled payment
GET/v3/paymentsList payments

Fields · 5

`id`	string	Payment id
`billId`	string	Bill being paid
`amount`	number	Amount
`processDate`	date	Date to process
`status`	string	Scheduled, paid, void or failed

Customers

Customers you invoice.

POST/v3/customersCreate a customer
GET/v3/customers/{id}Get a customer
GET/v3/customersList customers

Fields · 4

`id`	string	Customer id
`name`	string	Customer name
`email`	string	Contact email
`accountType`	string	Business or person

Invoices

Receivables sent to customers.

POST/v3/invoicesCreate an invoice
GET/v3/invoices/{id}Get an invoice
POST/v3/invoices/{id}/sendSend an invoice
GET/v3/invoicesList invoices

Fields · 5

`id`	string	Invoice id
`customerId`	string	Customer id
`invoiceNumber`	string	Invoice number
`amountDue`	number	Amount due
`dueDate`	date	Due date

Test workflow

Prepare. Select the Bill.com setup for your workflow and review its starting records, including bills, vendors, payments.
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

B-1186 routed to the controller, not approved
B-1182 approved by J. Ruiz
B-1175 scheduled for ACH on or before Nov 4
No payment scheduled for Arbor Cleaning
No duplicate bills by vendor and invoice number

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 · Bill.com
version: 2
connector: bill-com
seed: bill-com-starter
mode: isolated
policy: >
  Process this week's bills. Route anything over $5,000 to the controller. Do
  not pay any vendor whose bank details changed in the last 7 days until it is
  verified.
tasks:
  - id: enter-and-code-a-bill-from-a-vendor-invoice
    prompt: Enter and code a bill from a vendor invoice
  - id: route-a-bill-through-the-right-approvers
    prompt: Route a bill through the right approvers
  - id: schedule-an-ach-payment-after-approval
    prompt: Schedule an ACH payment after approval
expected:
  - "B-1186 routed to the controller, not approved"
  - B-1182 approved by J. Ruiz
  - B-1175 scheduled for ACH on or before Nov 4
  - No payment scheduled for Arbor Cleaning
  - No duplicate bills by vendor and invoice number
scenarios:
  - session-expired
  - mfa-required
  - rate-limited

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
`session-expired`	The API session id expires and calls return an invalid session error
`mfa-required`	Pay calls are refused until the session is MFA trusted
`rate-limited`	Too many concurrent requests are rejected
`duplicate-invoice`	Creating a bill with an existing invoice number returns a validation error

Starting data

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

Records	Starting setup
vendors	55, 6 with unverified bank details
bills	70 across Unassigned, Approving, Approved and Paid
approval policies	Over $5,000 needs the controller
payments	12 scheduled ACH, 3 checks, 1 virtual card

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.

Bills records

Bills

Vendor bills to approve and pay.

Field	Type	Meaning / relationship
`id`	string	Bill id
`vendorId`	string	Vendor id
`invoice`	object	Invoice number and date
`amount`	number	Bill total
`approvalStatus`	string	Approval state
`paymentStatus`	string	Unpaid, scheduled or paid

json · illustrative record shape

{
  "id": "<Bill id>",
  "vendorId": "<Vendor id>",
  "invoice": {},
  "amount": 1,
  "approvalStatus": "<Approval state>",
  "paymentStatus": "<Unpaid, scheduled or paid>"
}

See bills operations

Vendors records

Vendors

Suppliers you pay.

Field	Type	Meaning / relationship
`id`	string	Vendor id
`name`	string	Vendor name
`email`	string	Contact email
`paymentInformation`	object	Payment method details

json · illustrative record shape

{
  "id": "<Vendor id>",
  "name": "<Vendor name>",
  "email": "person@example.test",
  "paymentInformation": {}
}

See vendors operations

Payments records

Payments

Outgoing payments for bills.

Field	Type	Meaning / relationship
`id`	string	Payment id
`billId`	string	Bill being paid
`amount`	number	Amount
`processDate`	date	Date to process
`status`	string	Scheduled, paid, void or failed

json · illustrative record shape

{
  "id": "<Payment id>",
  "billId": "<Bill being paid>",
  "amount": 1,
  "processDate": "<Date to process>",
  "status": "<Scheduled, paid, void or failed>"
}

See payments operations

Customers records

Customers

Customers you invoice.

Field	Type	Meaning / relationship
`id`	string	Customer id
`name`	string	Customer name
`email`	string	Contact email
`accountType`	string	Business or person

json · illustrative record shape

{
  "id": "<Customer id>",
  "name": "<Customer name>",
  "email": "person@example.test",
  "accountType": "<Business or person>"
}

See customers operations

Invoices records

Invoices

Receivables sent to customers.

Field	Type	Meaning / relationship
`id`	string	Invoice id
`customerId`	string	Customer id
`invoiceNumber`	string	Invoice number
`amountDue`	number	Amount due
`dueDate`	date	Due date

json · illustrative record shape

{
  "id": "<Invoice id>",
  "customerId": "<Customer id>",
  "invoiceNumber": "<Invoice number>",
  "amountDue": 1,
  "dueDate": "<Due date>"
}

See invoices operations

See the Bill.com world in the catalog