For the complete documentation index, see llms.txt. This page is also available as Markdown.

Accounts

The Accounts API is the entry point for working with the customer organizations that own subscriptions, invoices, payment methods, and orders. An "account" in this API maps to a row in the platform's organizations table — but the same id space is also used for external billing accounts that live in the connected billing system (Zuora, Stripe, etc.) and are surfaced through the active billing adapter.

GET /api/v1/accounts/{id} is adapter-aware: if the id is not found locally and looks like a valid external billing-account id, the call is forwarded to the active adapter so that integrations can serve account detail without first having to copy every account into the platform.

All endpoints in this group require an API key with the appropriate scope (commerce for writes, read for reads). Every state-changing call writes an audit log entry (account.create, account.update) and returns a nextActions hint pointing to the natural follow-up endpoints (e.g. POST /subscriptions, GET /accounts/{id}/invoices).

See also: Subscriptions, Invoices, PaymentMethods.

Endpoints

POST /api/v1/accounts

Create a new account (organization)

post
/accounts
Authorizations
X-API-KeystringRequired

Scoped API key. Scopes: read, commerce, admin.

Body
namestringRequired
externalIdstringOptional
emailstringOptional
phonestringOptional
websitestringOptional
industrystringOptional
Responses
201

Account created

No content

post/accounts

No content

Creates a local organization row in the platform database. Use externalId to record the corresponding id in your billing system so that subsequent calls (subscriptions, invoices) can be correlated. The endpoint does not create an account in the connected billing adapter automatically — for that, push the new id through your adapter's onboarding flow or trigger a sync.

Requires the commerce API scope. Returns 201 with the new organization and a nextActions block suggesting POST /subscriptions or POST /payment-methods as the next step.

GET /api/v1/accounts/{id}

Get account details by ID. For external billing accounts, fetches from the billing adapter.

get
/accounts/{id}
Authorizations
X-API-KeystringRequired

Scoped API key. Scopes: read, commerce, admin.

Path parameters
idstringRequired
Responses
200

Account details

No content

get/accounts/{id}

No content

Two-phase lookup:

  1. First tries the local organizations table for the given id.

  2. If not found and id looks like a valid external billing-account id (per isValidAccountId), the request is forwarded to the active billing adapter (fetchAccountDetail) so that adapter-managed accounts resolve transparently.

Requires the read scope. Returns 404 only when both lookups miss. Adapter failures are swallowed (so they fall through to 404) — check the adapter health endpoint if you suspect a downstream outage.

PATCH /api/v1/accounts/{id}

Update account details

patch
/accounts/{id}
Authorizations
X-API-KeystringRequired

Scoped API key. Scopes: read, commerce, admin.

Path parameters
idstringRequired
Body
namestringOptional
emailstringOptional
phonestringOptional
Responses
200

Account updated

No content

patch/accounts/{id}

No content

Partial-update against the local organizations row. Only the fields supplied in the request body are written; omitted fields are left untouched. This endpoint does not propagate changes to the connected billing adapter — for adapter-managed fields (billing email, tax id, etc.), drive the change through the adapter's account-update flow.

Requires the commerce scope. Returns 404 if the id is not a local organization (adapter-only accounts cannot be patched here).

Last updated

Was this helpful?