Balance API

Get account balances and perform simple balance adjustments (add / deduct). Reservation workflows live in the Reservations API.

Account-Centric API

All credit operations are scoped to a specific account. You can use either the internal account ID (from Credits) or your externalId (your own user/customer ID) for lookups.

GET/v1/accounts/balance?accountId=...

Get the current credit balance for an account, including reserved and available amounts.

Get account balance

curl -X GET "https://api.credits.dev/v1/accounts/balance?accountId=acc_123" \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "accountId": "acc_123",
  "externalId": "user_123",
  "balance": 1000,
  "reserved": 150,
  "available": 850
}

GET/v1/accounts/balance?externalId=...

Get balance using externalId query parameter.

Get balance by externalId

curl -X GET "https://api.credits.dev/v1/accounts/balance?externalId=user_123" \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "accountId": "acc_123",
  "externalId": "user_123",
  "balance": 1000,
  "reserved": 150,
  "available": 850
}

POST/v1/accounts/credits/add

Add credits to an account balance. Use for purchases, refunds, or bonuses.

Add credits to account balance

curl -X POST "https://api.credits.dev/v1/accounts/credits/add" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_123",
    "amount": 500,
    "description": "Credit purchase",
    "paymentMethod": "stripe"
  }'

Request Body

{
  "accountId": "acc_123",
  "amount": 500,
  "description": "Credit purchase",
  "paymentMethod": "stripe",
  "metadata": {
    "paymentId": "pay_123"
  }
}

Response

{
  "success": true,
  "accountId": "acc_123",
  "externalId": "user_123",
  "balance": 1500,
  "added": 500
}

POST/v1/accounts/credits/deduct

Deduct credits from an account balance. Use for simple deductions without reservations.

Deduct credits from account balance

curl -X POST "https://api.credits.dev/v1/accounts/credits/deduct" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_123",
    "amount": 50,
    "description": "API call - chat completion",
    "metadata": {
      "action": "chat-completion"
    }
  }'

Request Body

{
  "accountId": "acc_123",
  "amount": 50,
  "description": "API call - chat completion",
  "metadata": {
    "action": "chat-completion"
  }
}

Response

{
  "success": true,
  "accountId": "acc_123",
  "externalId": "user_123",
  "balance": 950,
  "deducted": 50
}