Accounts API

Manage customer accounts and their credit balances.

Dual ID Support

Every account has both an internal ID (generated by Credits) and an externalId (your own user/customer ID). You can operate on accounts using either identifier, making it easy to integrate with your existing systems.

POST/v1/accounts/create

Create a new account with your externalId for easy mapping to your user system.

Create account with externalId

curl -X POST "https://api.credits.dev/v1/accounts/create" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "externalId": "user_123",
    "email": "john@example.com"
  }'

Request Body

{
  "name": "John Doe",
  "externalId": "user_123",
  "email": "john@example.com",
  "metadata": {
    "plan": "premium",
    "company": "Acme Corp"
  }
}

Response

{
  "success": true,
  "account": {
    "id": "acc_abc123",
    "developerId": "dev_xxx",
    "externalId": "user_123",
    "name": "John Doe",
    "email": "john@example.com",
    "balance": 0,
    "metadata": null,
    "createdAt": "2024-01-15T10:00:00Z",
    "updatedAt": "2024-01-15T10:00:00Z"
  }
}

GET/v1/accounts

List all accounts for your project.

List accounts

curl -X GET "https://api.credits.dev/v1/accounts" \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "accounts": [
    {
      "id": "acc_abc123",
      "developerId": "dev_xxx",
      "externalId": "user_123",
      "name": "John Doe",
      "email": "john@example.com",
      "balance": 500,
      "metadata": null,
      "createdAt": "2024-01-15T10:00:00Z",
      "updatedAt": "2024-01-15T10:00:00Z"
    }
  ]
}

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

Get a single account by internal account ID or externalId.

Get account by ID

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

Response

{
  "id": "acc_abc123",
  "developerId": "dev_xxx",
  "externalId": "user_123",
  "name": "John Doe",
  "email": "john@example.com",
  "balance": 500,
  "metadata": null,
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T10:00:00Z"
}

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
}