Worlds / Payments and billing

Chargebee API

A local Chargebee site with customers, subscriptions, item prices, invoices, credit notes and dunning. Test the agent that changes plans with proration, extends trials and handles failed payments.

Base path: /api/v2
Auth: Basic auth with API key as username, the world key
Endpoints: 17
Status: Active today

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

js · chargebee

import chargebee from "chargebee";

chargebee.configure({
  site: "acme-test",
  api_key: process.env.WORLDS_API_KEY,
  protocol: "http",
  hostSuffix: process.env.WORLDS_CHARGEBEE_URL,
});

const { subscription } = await chargebee.subscription
  .retrieve("sub_123")
  .request();

API reference

17 of 17

Customers

Billing accounts with contact and payment details.

POST/api/v2/customersCreate a customer
GET/api/v2/customers/{id}Retrieve a customer
POST/api/v2/customers/{id}Update a customer
GET/api/v2/customersList customers

Fields · 5

`id`	string	Customer id
`email`	string	Email address
`first_name`	string	First name
`auto_collection`	string	on or off
`balances`	array	Promotional and refundable credits

Subscriptions

Recurring plans attached to a customer.

POST/api/v2/customers/{customer_id}/subscription_for_itemsCreate a subscription for a customer
GET/api/v2/subscriptions/{id}Retrieve a subscription
POST/api/v2/subscriptions/{id}/update_for_itemsUpdate a subscription
POST/api/v2/subscriptions/{id}/cancel_for_itemsCancel a subscription
GET/api/v2/subscriptionsList subscriptions

Fields · 5

`id`	string	Subscription id
`customer_id`	string	Customer id
`status`	string	active, in_trial, cancelled, non_renewing and more
`subscription_items`	array	Item prices and quantities
`next_billing_at`	timestamp	Next renewal

Invoices

Charges raised from subscriptions and one-time items.

GET/api/v2/invoices/{id}Retrieve an invoice
POST/api/v2/invoices/{id}/collect_paymentCollect payment on an invoice
POST/api/v2/invoices/{id}/record_paymentRecord an offline payment
POST/api/v2/invoices/{id}/voidVoid an invoice
GET/api/v2/invoicesList invoices

Fields · 5

`id`	string	Invoice id
`status`	string	paid, posted, payment_due, not_paid or voided
`total`	integer	Total in minor units
`amount_due`	integer	Outstanding amount
`customer_id`	string	Customer id

Credit notes

Credits and refunds against invoices.

POST/api/v2/credit_notesCreate a credit note
POST/api/v2/credit_notes/{id}/refundRefund a credit note
GET/api/v2/credit_notesList credit notes

Fields · 4

`id`	string	Credit note id
`reference_invoice_id`	string	Invoice credited
`type`	string	adjustment or refundable
`total`	integer	Credit total

Test workflow

Prepare. Select the Chargebee setup for your workflow and review its starting records, including customers, 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

Nori Health on Growth with a prorated charge for the remaining days
Pike & Vale trial_end moved 14 days later
Okto Labs still Active with cancel scheduled at end_of_term
No credit note created for Okto Labs
No other subscription changed

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 · Chargebee
version: 2
connector: chargebee
seed: chargebee-starter
mode: isolated
policy: >
  Upgrade Nori Health from Starter to Growth today with proration. Extend Pike
  & Vale's trial by 14 days. Okto Labs asked to cancel at the end of their
  term, not now.
tasks:
  - id: upgrade-a-subscription-with-the-right-proration
    prompt: Upgrade a subscription with the right proration
  - id: extend-a-trial-or-pause-a-subscription
    prompt: Extend a trial or pause a subscription
  - id: resolve-an-invoice-stuck-in-dunning
    prompt: Resolve an invoice stuck in dunning
expected:
  - Nori Health on Growth with a prorated charge for the remaining days
  - "Pike & Vale trial_end moved 14 days later"
  - Okto Labs still Active with cancel scheduled at end_of_term
  - No credit note created for Okto Labs
  - No other subscription changed
scenarios:
  - rate-limited
  - wrong-state
  - payment-failed

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
`rate-limited`	API returns 429 api_request_limit_exceeded
`wrong-state`	Changing a cancelled subscription returns invalid_state_for_request
`payment-failed`	payment_failed webhook fires during the upgrade
`not-found`	An old item price id returns resource_not_found

Starting data

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

Records	Starting setup
subscriptions	90 across in_trial, active, non_renewing, paused and cancelled
item prices	Starter, Growth and Scale, monthly and yearly
invoices	200 paid, 7 payment_due, 3 not_paid
credit notes	5 adjustment, 2 refundable
coupons	3 active including WELCOME20

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

Billing accounts with contact and payment details.

Field	Type	Meaning / relationship
`id`	string	Customer id
`email`	string	Email address
`first_name`	string	First name
`auto_collection`	string	on or off
`balances`	array	Promotional and refundable credits

json · illustrative record shape

{
  "id": "<Customer id>",
  "email": "person@example.test",
  "first_name": "<First name>",
  "auto_collection": "<on or off>",
  "balances": []
}

See customers operations

Subscriptions records

Subscriptions

Recurring plans attached to a customer.

Field	Type	Meaning / relationship
`id`	string	Subscription id
`customer_id`	string	Customer id
`status`	string	active, in_trial, cancelled, non_renewing and more
`subscription_items`	array	Item prices and quantities
`next_billing_at`	timestamp	Next renewal

json · illustrative record shape

{
  "id": "<Subscription id>",
  "customer_id": "<Customer id>",
  "status": "<active, in_trial, cancelled, non_renewing and more>",
  "subscription_items": [],
  "next_billing_at": "<Next renewal>"
}

See subscriptions operations

Invoices records

Invoices

Charges raised from subscriptions and one-time items.

Field	Type	Meaning / relationship
`id`	string	Invoice id
`status`	string	paid, posted, payment_due, not_paid or voided
`total`	integer	Total in minor units
`amount_due`	integer	Outstanding amount
`customer_id`	string	Customer id

json · illustrative record shape

{
  "id": "<Invoice id>",
  "status": "<paid, posted, payment_due, not_paid or voided>",
  "total": 1,
  "amount_due": 1,
  "customer_id": "<Customer id>"
}

See invoices operations

Credit notes records

Credit notes

Credits and refunds against invoices.

Field	Type	Meaning / relationship
`id`	string	Credit note id
`reference_invoice_id`	string	Invoice credited
`type`	string	adjustment or refundable
`total`	integer	Credit total

json · illustrative record shape

{
  "id": "<Credit note id>",
  "reference_invoice_id": "<Invoice credited>",
  "type": "<adjustment or refundable>",
  "total": 1
}

See credit notes operations

See the Chargebee world in the catalog