Worlds / Payments and billing

Zuora API

A local Zuora tenant with accounts, subscriptions, rate plans, bill runs, payment runs and revenue schedules. Test the agent that amends subscriptions and schedules bill runs without billing customers twice.

Base path: /v1
Auth: OAuth bearer token, the world key
Endpoints: 16
Status: Active today

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

js · fetch

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

const res = await fetch(base + "/v1/accounts/A00000001", { headers });
const account = await res.json();

API reference

16 of 16

Accounts

Customer billing accounts.

POST/v1/accountsCreate an account
GET/v1/accounts/{account-key}Get an account
PUT/v1/accounts/{account-key}Update an account
GET/v1/accounts/{account-key}/summaryGet an account summary

Fields · 5

`id`	string	Account id
`accountNumber`	string	Account number
`name`	string	Account name
`balance`	number	Current balance
`currency`	string	Billing currency

Subscriptions

Product rate plans billed to an account.

POST/v1/subscriptionsCreate a subscription
GET/v1/subscriptions/{subscription-key}Get a subscription
PUT/v1/subscriptions/{subscription-key}Update a subscription
PUT/v1/subscriptions/{subscription-key}/cancelCancel a subscription

Fields · 5

`id`	string	Subscription id
`subscriptionNumber`	string	Subscription number
`status`	string	Active, Cancelled or Suspended
`termType`	string	TERMED or EVERGREEN
`contractEffectiveDate`	date	Start date

Invoices

Bills generated for an account.

GET/v1/invoices/{invoice-key}Get an invoice
GET/v1/accounts/{account-key}/invoicesList invoices for an account
PUT/v1/invoices/{invoice-key}/write-offWrite off an invoice
POST/v1/object/invoiceCreate an invoice

Fields · 5

`id`	string	Invoice id
`invoiceNumber`	string	Invoice number
`status`	string	Draft, Posted or Canceled
`amount`	number	Total amount
`balance`	number	Remaining balance

Payments

Payments applied to invoices.

POST/v1/paymentsCreate a payment
GET/v1/payments/{payment-key}Get a payment
POST/v1/payments/{payment-key}/refundsRefund a payment
GET/v1/paymentsList payments

Fields · 4

`id`	string	Payment id
`accountId`	string	Account id
`amount`	number	Amount paid
`status`	string	Processed, Error or Draft

Test workflow

Prepare. Select the Zuora setup for your workflow and review its starting records, including accounts, subscriptions, invoices.
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

BR-0413 canceled, BR-0412 still Completed
No account has two invoices for the same period
BR-0415 rescheduled to Thu 5 at 06:00
No payment run targets Draft invoices
Subscription versions unchanged on accounts outside the brief

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 · Zuora
version: 2
connector: zuora
seed: zuora-starter
mode: isolated
policy: >
  A duplicate bill run was created for cycle day 1. Cancel the duplicate and
  keep the first. Move the EU run to Thursday morning, and only collect on
  posted invoices.
tasks:
  - id: amend-a-subscription-to-add-or-remove-a-rate-plan
    prompt: Amend a subscription to add or remove a rate plan
  - id: schedule-or-cancel-a-bill-run
    prompt: Schedule or cancel a bill run
  - id: post-invoices-and-start-a-payment-run
    prompt: Post invoices and start a payment run
expected:
  - "BR-0413 canceled, BR-0412 still Completed"
  - No account has two invoices for the same period
  - "BR-0415 rescheduled to Thu 5 at 06:00"
  - No payment run targets Draft invoices
  - Subscription versions unchanged on accounts outside the brief
scenarios:
  - lock-competition
  - rate-limited
  - invalid-value

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
`lock-competition`	Two writes to the same account return LOCK_COMPETITION
`rate-limited`	REST API returns 429 under bulk amendments
`invalid-value`	An order with a past effective date returns INVALID_VALUE
`bill-run-error`	A bill run ends in Error for 3 accounts with missing bill-to contacts

Starting data

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

Records	Starting setup
accounts	75 across 3 bill cycle days
subscriptions	120 with recurring and usage rate plan charges
bill runs	2 Completed, 1 Pending, 1 scheduled
invoices	300 Posted, 18 Draft
revenue schedules	Ratable over 12 months for annual plans

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.

Accounts records

Accounts

Customer billing accounts.

Field	Type	Meaning / relationship
`id`	string	Account id
`accountNumber`	string	Account number
`name`	string	Account name
`balance`	number	Current balance
`currency`	string	Billing currency

json · illustrative record shape

{
  "id": "<Account id>",
  "accountNumber": "<Account number>",
  "name": "<Account name>",
  "balance": 1,
  "currency": "<Billing currency>"
}

See accounts operations

Subscriptions records

Subscriptions

Product rate plans billed to an account.

Field	Type	Meaning / relationship
`id`	string	Subscription id
`subscriptionNumber`	string	Subscription number
`status`	string	Active, Cancelled or Suspended
`termType`	string	TERMED or EVERGREEN
`contractEffectiveDate`	date	Start date

json · illustrative record shape

{
  "id": "<Subscription id>",
  "subscriptionNumber": "<Subscription number>",
  "status": "<Active, Cancelled or Suspended>",
  "termType": "<TERMED or EVERGREEN>",
  "contractEffectiveDate": "<Start date>"
}

See subscriptions operations

Invoices records

Invoices

Bills generated for an account.

Field	Type	Meaning / relationship
`id`	string	Invoice id
`invoiceNumber`	string	Invoice number
`status`	string	Draft, Posted or Canceled
`amount`	number	Total amount
`balance`	number	Remaining balance

json · illustrative record shape

{
  "id": "<Invoice id>",
  "invoiceNumber": "<Invoice number>",
  "status": "<Draft, Posted or Canceled>",
  "amount": 1,
  "balance": 1
}

See invoices operations

Payments records

Payments

Payments applied to invoices.

Field	Type	Meaning / relationship
`id`	string	Payment id
`accountId`	string	Account id
`amount`	number	Amount paid
`status`	string	Processed, Error or Draft

json · illustrative record shape

{
  "id": "<Payment id>",
  "accountId": "<Account id>",
  "amount": 1,
  "status": "<Processed, Error or Draft>"
}

See payments operations

See the Zuora world in the catalog