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

https://peakcommerce.app/api/v1https://sandbox.peakcommerce.app/api/v1

/accounts/{id}/credit-balance

Authorizations

ApiKeyAuthBearerAuth

X-API-KeystringRequired

Scoped API key. Scopes: read, commerce, admin.

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)

404

Account not found

application/json

get/accounts/{id}/credit-balance

HTTPcURLJavaScriptPython

GET /api/v1/accounts/{id}/credit-balance HTTP/1.1
Host: 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

https://peakcommerce.app/api/v1https://sandbox.peakcommerce.app/api/v1

/accounts/{id}/credits

Authorizations

ApiKeyAuthBearerAuth

X-API-KeystringRequired

Scoped API key. Scopes: read, commerce, admin.

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

404

Account not found

application/json

get/accounts/{id}/credits

HTTPcURLJavaScriptPython

GET /api/v1/accounts/{id}/credits HTTP/1.1
Host: 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

https://peakcommerce.app/api/v1https://sandbox.peakcommerce.app/api/v1

/accounts/{id}/credits

Authorizations

ApiKeyAuthBearerAuth

X-API-KeystringRequired

Scoped API key. Scopes: read, commerce, admin.

Path parameters

idstringRequired

Account (organization) ID

Body

application/json

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

400

Validation error

application/json

404

Account not found

application/json

post/accounts/{id}/credits

HTTPcURLJavaScriptPython

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

{
  "amountCents": 1,
  "currency": "USD",
  "reason": "text",
  "expiresAt": "2026-07-13T23:44:16.171Z"
}

{
  "id": "text",
  "accountId": "text",
  "amountCents": 1,
  "remainingCents": 1,
  "currency": "text",
  "status": "active",
  "reason": "text",
  "expiresAt": "2026-07-13T23:44:16.171Z",
  "createdAt": "2026-07-13T23:44:16.171Z",
  "updatedAt": "2026-07-13T23:44:16.171Z",
  "applications": [
    {
      "paymentId": "text",
      "amountCents": 1,
      "appliedAt": "2026-07-13T23:44:16.171Z"
    }
  ]
}

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

https://peakcommerce.app/api/v1https://sandbox.peakcommerce.app/api/v1

/accounts/{id}/credits/{creditId}/apply

Authorizations

ApiKeyAuthBearerAuth

X-API-KeystringRequired

Scoped API key. Scopes: read, commerce, admin.

Path parameters

idstringRequired

Account ID

creditIdstringRequired

Credit ID

Body

application/json

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

400

Credit not active, expired, or exhausted

application/json

404

Account, credit, or payment session not found

application/json

post/accounts/{id}/credits/{creditId}/apply

HTTPcURLJavaScriptPython

POST /api/v1/accounts/{id}/credits/{creditId}/apply HTTP/1.1
Host: 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-07-13T23:44:16.171Z",
  "createdAt": "2026-07-13T23:44:16.171Z",
  "updatedAt": "2026-07-13T23:44:16.171Z",
  "applications": [
    {
      "paymentId": "text",
      "amountCents": 1,
      "appliedAt": "2026-07-13T23:44:16.171Z"
    }
  ]
}

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