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 secret API key — send an sk_live_… value (keys issued before the typed format carry a bare pk_<hex> prefix and are also secret; they still work). A publishable pk_live_…/pk_test_… key is browser-safe, carries no scopes, and is refused by every endpoint in this spec with publishable_key_not_allowed. Coarse scopes: read, commerce, admin (admin covers everything below). Narrow per-resource scopes: journeys|pages :read|write|publish|delete, productsets :read|write|publish|delete, components|rules :read|write|delete, context :read (read-only context tier), catalog :read|write-native. publish is never implied by write.

Body

namestringRequired

externalIdstringOptional

emailstringOptional

phonestringOptional

websitestringOptional

industrystringOptional

Responses

201

Account created

No content

400

Validation error

post/accounts

POST /api/v1/accounts HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 100

{
  "name": "text",
  "externalId": "text",
  "email": "text",
  "phone": "text",
  "website": "text",
  "industry": "text"
}

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 secret API key — send an sk_live_… value (keys issued before the typed format carry a bare pk_<hex> prefix and are also secret; they still work). A publishable pk_live_…/pk_test_… key is browser-safe, carries no scopes, and is refused by every endpoint in this spec with publishable_key_not_allowed. Coarse scopes: read, commerce, admin (admin covers everything below). Narrow per-resource scopes: journeys|pages :read|write|publish|delete, productsets :read|write|publish|delete, components|rules :read|write|delete, context :read (read-only context tier), catalog :read|write-native. publish is never implied by write.

Path parameters

idstringRequired

Responses

200

Account details

No content

404

Account not found

get/accounts/{id}

GET /api/v1/accounts/{id} HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

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 secret API key — send an sk_live_… value (keys issued before the typed format carry a bare pk_<hex> prefix and are also secret; they still work). A publishable pk_live_…/pk_test_… key is browser-safe, carries no scopes, and is refused by every endpoint in this spec with publishable_key_not_allowed. Coarse scopes: read, commerce, admin (admin covers everything below). Narrow per-resource scopes: journeys|pages :read|write|publish|delete, productsets :read|write|publish|delete, components|rules :read|write|delete, context :read (read-only context tier), catalog :read|write-native. publish is never implied by write.

Path parameters

idstringRequired

Body

namestringOptional

emailstringOptional

phonestringOptional

Responses

200

Account updated

No content

404

Not found

patch/accounts/{id}

PATCH /api/v1/accounts/{id} HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 45

{
  "name": "text",
  "email": "text",
  "phone": "text"
}

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).