Invoices

The Invoices API is a thin pass-through over the active billing adapter — invoices live in the connected billing system (Zuora, Stripe Billing, etc.), not in the platform database, and this API surfaces them per-account and offers a one-shot "pay this invoice" entry point.

The two endpoints in this group are the high-traffic ones for a customer portal: list the invoices on an account, then start a payment session for a specific open invoice. The payment-session lifecycle then continues under Payments.

Reads require the read scope; the pay endpoint requires commerce. Adapter outages surface as 502; missing accounts surface as 404.

Endpoints

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

List all invoices for an account via the billing adapter

get

/accounts/{id}/invoices

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

Query parameters

limitinteger · min: 1 · max: 100Optional

Max items to return (1–100, default 20)

Default: 20

offsetintegerOptional

Number of items to skip (default 0)

Default: 0

sortstringOptional

Field to sort by

sortDirstring · enumOptional

Sort direction

Default: ascPossible values:

Responses

200

Paginated list of invoices

401

API key missing or invalid

application/json

404

No billing integration configured

application/json

get/accounts/{id}/invoices

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

No content

Returns every invoice for the given account, sourced from the active billing adapter (fetchInvoices). The id must be a valid external billing-account id — invoices are not stored locally, so a local-only organizations.id will not resolve invoices unless the row also carries an externalId.

Each entry includes the adapter's invoice id, status (open / paid / void / uncollectible), amount, currency, due date, and a hosted-invoice URL when the gateway provides one. Pair with POST /invoices/{id}/pay for the open ones.

Requires the read scope.

POST /api/v1/invoices/{id}/pay

Initiate payment for a specific invoice

post

/invoices/{id}/pay

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

accountIdstringRequired

amountCentsintegerRequired

currencystringRequired

Responses

201

Payment session created for invoice

No content

post/invoices/{id}/pay

POST /api/v1/invoices/{id}/pay HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 54

{
  "accountId": "text",
  "amountCents": 1,
  "currency": "text"
}

201

Payment session created for invoice

No content

Convenience wrapper that opens a payment session bound to a specific invoice. Equivalent to POST /payments with invoiceId set, but takes the invoice id from the URL and lets you pass accountId, amountCents, and currency explicitly to avoid an extra adapter round-trip.

The returned 201 carries the new payment session — continue the flow under Payments. On complete, the linked invoice is settled through the active billing adapter.

Requires the commerce scope.