> For the complete documentation index, see [llms.txt](https://docs.peakcommerce.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.peakcommerce.com/developers/api-groups/accounts.md).

# 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](/developers/api-groups/subscriptions.md), [Invoices](/developers/api-groups/invoices.md), [PaymentMethods](/developers/api-groups/paymentmethods.md).

## Endpoints

### `POST /api/v1/accounts`

{% openapi src="<https://api.peakcommerce.com/api/v1/openapi.json>" path="/accounts" method="post" %}
<https://api.peakcommerce.com/api/v1/openapi.json>
{% endopenapi %}

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}`

{% openapi src="<https://api.peakcommerce.com/api/v1/openapi.json>" path="/accounts/{id}" method="get" %}
<https://api.peakcommerce.com/api/v1/openapi.json>
{% endopenapi %}

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}`

{% openapi src="<https://api.peakcommerce.com/api/v1/openapi.json>" path="/accounts/{id}" method="patch" %}
<https://api.peakcommerce.com/api/v1/openapi.json>
{% endopenapi %}

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.peakcommerce.com/developers/api-groups/accounts.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.