Accounts

An account is a customer organization. Accounts hold subscriptions, invoices, payment methods, and contacts.

• POST /api/v1/accounts — create

• GET /api/v1/accounts/{id} — retrieve

• PATCH /api/v1/accounts/{id} — update

• GET /api/v1/accounts/{id}/invoices

• GET /api/v1/accounts/{id}/subscriptions

• GET /api/v1/accounts/{id}/payment-methods

---

POST /api/v1/accounts

Create a new account in this tenant.

• Auth scope: commerce

Body

Field	Type	Required	Description
name	string (1–255)	yes	Account display name
externalId	string (≤255)	no	Your external system ID
email	string (email)	no	Primary email
phone	string (≤50)	no
website	string (≤500)	no
industry	string (≤100)	no

Response 201

{
  "data": {
    "id": "org_01H...",
    "tenantId": "ten_01H...",
    "name": "Acme Inc.",
    "externalId": "crm_42",
    "email": "[e-mail]",
    "phone": null,
    "website": "https://acme.com",
    "industry": "SaaS",
    "createdAt": "2026-05-02T14:01:23Z",
    "updatedAt": "2026-05-02T14:01:23Z"
  },
  "nextActions": [
    { "rel": "self", "method": "GET", "href": "/api/v1/accounts/org_01H..." },
    { "rel": "update", "method": "PATCH", "href": "/api/v1/accounts/org_01H..." },
    { "rel": "invoices", "method": "GET", "href": "/api/v1/accounts/org_01H.../invoices" },
    { "rel": "subscriptions", "method": "GET", "href": "/api/v1/accounts/org_01H.../subscriptions" },
    { "rel": "paymentMethods", "method": "GET", "href": "/api/v1/accounts/org_01H.../payment-methods" }
  ]
}

Errors

Status	When
400	Validation failed
401 / 403	Auth / scope
500	Server error

cURL

curl -X POST https://api.example.com/api/v1/accounts \
  -H "Authorization: Bearer $PEAK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc.",
    "externalId": "crm_42",
    "email": "[e-mail]",
    "website": "https://acme.com",
    "industry": "SaaS"
  }'

---

GET /api/v1/accounts/{id}

Retrieve an account by ID. The platform first looks for a tenant-owned organization; if none exists and the ID is a valid billing-system account ID, the call falls through to the active billing adapter.

• Auth scope: read

Path

Param	Description
id	Internal organization UUID or billing-system account ID

Response 200

{
  "data": {
    "id": "org_01H...",
    "name": "Acme Inc.",
    "externalId": "crm_42",
    "email": "[e-mail]",
    "phone": null,
    "website": "https://acme.com",
    "industry": "SaaS",
    "createdAt": "2026-05-02T14:01:23Z"
  },
  "nextActions": [ /* see POST */ ]
}

When resolved through the billing adapter, the data shape matches the adapter's account-detail response (account number, balance, contacts).

Errors

Status	When
404	No matching account in this tenant or billing system

cURL

curl -H "Authorization: Bearer $PEAK_API_KEY" \
  https://api.example.com/api/v1/accounts/org_01H...

---

PATCH /api/v1/accounts/{id}

Update fields on a tenant-owned account.

• Auth scope: commerce

Body (all optional)

Field	Type
name	string (1–255)
email	string (email)
phone	string (≤50)
website	string (≤500)
industry	string (≤100)

Response 200

Same shape as GET.

Errors

Status	When
400	Validation failed
404	Account not found in this tenant

cURL

curl -X PATCH https://api.example.com/api/v1/accounts/org_01H... \
  -H "Authorization: Bearer $PEAK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "[phone]" }'

---

GET /api/v1/accounts/{id}/invoices

List all invoices for an account, fetched live from the active billing adapter.

• Auth scope: read

Path

Param	Description
id	Billing-system account ID (must match billing-system format)

Response 200

{
  "data": [
    {
      "id": "INV-0001",
      "invoiceNumber": "INV-0001",
      "invoiceDate": "2026-04-01",
      "dueDate": "2026-04-15",
      "amount": 49.00,
      "balance": 0.00,
      "currency": "USD",
      "status": "paid"
    }
  ],
  "nextActions": [
    { "rel": "createPaymentSession", "method": "POST", "href": "/api/v1/payments" }
  ]
}

Errors

Status	When
400	Invalid account ID format
404	No active billing integration configured

cURL

curl -H "Authorization: Bearer $PEAK_API_KEY" \
  https://api.example.com/api/v1/accounts/A00000123/invoices

---

GET /api/v1/accounts/{id}/subscriptions

List subscriptions for an account, fetched live from the active billing adapter.

• Auth scope: read

Response 200

{
  "data": [
    {
      "id": "sub_01H...",
      "status": "active",
      "priceCents": 4900,
      "currency": "USD",
      "billingInterval": "month"
    }
  ],
  "nextActions": [
    { "rel": "createSubscription", "method": "POST", "href": "/api/v1/subscriptions" },
    { "rel": "catalog", "method": "GET", "href": "/api/v1/catalog" }
  ]
}

Errors

Status	When
400	Invalid account ID format
404	No active billing integration configured

cURL

curl -H "Authorization: Bearer $PEAK_API_KEY" \
  https://api.example.com/api/v1/accounts/A00000123/subscriptions

---

GET /api/v1/accounts/{id}/payment-methods

List payment methods for an account, fetched live from the active billing adapter.

• Auth scope: read

Response 200

{
  "data": [
    {
      "id": "pm_01H...",
      "type": "card",
      "cardType": "visa",
      "lastFour": "4242",
      "expirationMonth": 12,
      "expirationYear": 2028,
      "isDefault": true
    }
  ],
  "nextActions": [
    { "rel": "addPaymentMethod", "method": "POST", "href": "/api/v1/payment-methods" }
  ]
}

Errors

Status	When
400	Invalid account ID format
404	No active billing integration configured

cURL

curl -H "Authorization: Bearer $PEAK_API_KEY" \
  https://api.example.com/api/v1/accounts/A00000123/payment-methods

---

Related

• Subscriptions

• Payments