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
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.
Account ID
Credit balance summary
Aggregate credit balance for an account
Total active, non-expired credit balance in cents
Number of active non-expired credits
Number of credits that have expired
Total credit records (all statuses)
Account not found
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
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.
Account ID
Max items to return (1–100, default 20)
20Number of items to skip (default 0)
0Paginated list of credits
No content
Account not found
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.
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.
Account (organization) ID
3-letter ISO 4217 currency code
USDISO 8601 expiry timestamp. Omit for a non-expiring credit.
Credit issued
A credit issued to an account that can be applied to reduce future payment amounts
Original credit amount
Remaining unapplied balance
Validation error
Account not found
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
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.
Account ID
Credit ID
Payment session ID to apply the credit against. Omit to record an unallocated application.
Partial application amount. Omit to apply the full remaining balance.
Credit applied
A credit issued to an account that can be applied to reduce future payment amounts
Original credit amount
Remaining unapplied balance
Credit not active, expired, or exhausted
Account, credit, or payment session not found
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?
