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

Credits

Credits represent prepaid or goodwill balances attached to an account. Issue a credit, list outstanding credits, check the aggregate balance, or apply a credit against a payment session.

As of Task #1454, credits are stored in their own account_credits table (with a child credit_applications table for the application history) rather than inside organizations.metadata. The HTTP contract is unchanged — only the backing store moved — so existing API clients require no updates.

Endpoints

GET /api/v1/accounts/{id}/credit-balance

Get the aggregate credit balance for an account — sum of all active, non-expired credits

get
/accounts/{id}/credit-balance
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

Account ID

Responses
200

Credit balance summary

application/json

Aggregate credit balance for an account

accountIdstringOptional
balanceCentsintegerOptional

Total active, non-expired credit balance in cents

currencystringOptional
activeCreditsintegerOptional

Number of active non-expired credits

expiredCreditsintegerOptional

Number of credits that have expired

totalCreditsintegerOptional

Total credit records (all statuses)

get/accounts/{id}/credit-balance
GET /api/v1/accounts/{id}/credit-balance HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*
{
  "accountId": "text",
  "balanceCents": 1,
  "currency": "text",
  "activeCredits": 1,
  "expiredCredits": 1,
  "totalCredits": 1
}

Notes, examples, or caveats for GET /accounts/{id}/credit-balance go here.

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

List credits for an account

get
/accounts/{id}/credits
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

Account ID

Query parameters
statusstring · enumOptionalPossible values:
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
Responses
200

Paginated list of credits

No content

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

No content

Notes, examples, or caveats for GET /accounts/{id}/credits go here.

POST /api/v1/accounts/{id}/credits

Issue a credit to an account. Credits reduce the amount due on future payments when applied.

post
/accounts/{id}/credits
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

Account (organization) ID

Body
amountCentsinteger · min: 1Required
currencystringOptional

3-letter ISO 4217 currency code

Default: USD
reasonstring · max: 500Optional
expiresAtstring · date-timeOptional

ISO 8601 expiry timestamp. Omit for a non-expiring credit.

Responses
201

Credit issued

application/json

A credit issued to an account that can be applied to reduce future payment amounts

idstringOptional
accountIdstringOptional
amountCentsintegerOptional

Original credit amount

remainingCentsintegerOptional

Remaining unapplied balance

currencystringOptional
statusstring · enumOptionalPossible values:
reasonstring · nullableOptional
expiresAtstring · date-time · nullableOptional
createdAtstring · date-timeOptional
updatedAtstring · date-timeOptional
post/accounts/{id}/credits
POST /api/v1/accounts/{id}/credits HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 89

{
  "amountCents": 1,
  "currency": "USD",
  "reason": "text",
  "expiresAt": "2026-01-01T00:00:00.000Z"
}
{
  "id": "text",
  "accountId": "text",
  "amountCents": 1,
  "remainingCents": 1,
  "currency": "text",
  "status": "active",
  "reason": "text",
  "expiresAt": "2026-01-01T00:00:00.000Z",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "applications": [
    {
      "paymentId": "text",
      "amountCents": 1,
      "appliedAt": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Notes, examples, or caveats for POST /accounts/{id}/credits go here.

POST /api/v1/accounts/{id}/credits/{creditId}/apply

Apply a credit (or a portion of it) to a payment session

post
/accounts/{id}/credits/{creditId}/apply
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

Account ID

creditIdstringRequired

Credit ID

Body
paymentIdstringOptional

Payment session ID to apply the credit against. Omit to record an unallocated application.

amountCentsinteger · min: 1Optional

Partial application amount. Omit to apply the full remaining balance.

Responses
200

Credit applied

application/json

A credit issued to an account that can be applied to reduce future payment amounts

idstringOptional
accountIdstringOptional
amountCentsintegerOptional

Original credit amount

remainingCentsintegerOptional

Remaining unapplied balance

currencystringOptional
statusstring · enumOptionalPossible values:
reasonstring · nullableOptional
expiresAtstring · date-time · nullableOptional
createdAtstring · date-timeOptional
updatedAtstring · date-timeOptional
post/accounts/{id}/credits/{creditId}/apply
POST /api/v1/accounts/{id}/credits/{creditId}/apply HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 36

{
  "paymentId": "text",
  "amountCents": 1
}
{
  "id": "text",
  "accountId": "text",
  "amountCents": 1,
  "remainingCents": 1,
  "currency": "text",
  "status": "active",
  "reason": "text",
  "expiresAt": "2026-01-01T00:00:00.000Z",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "applications": [
    {
      "paymentId": "text",
      "amountCents": 1,
      "appliedAt": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Notes, examples, or caveats for POST /accounts/{id}/credits/{creditId}/apply go here.

Last updated

Was this helpful?