3 min read

Get Credit Balance

Retrieve your current credit balance with breakdown by credit type

Retrieve your current credit balance, including total credits, used credits, and remaining credits with a breakdown by credit type.

GET/v1/credits/balance

Request

Headers

ParameterTypeDescription
X-API-Keyrequired
stringYour API key for authentication

Example Requests

curl
curl -X GET https://api.docurift.com/v1/credits/balance \
-H "X-API-Key: frc_your_api_key_here"
python
import requests
import os

API_KEY = os.getenv('DOCURIFT_API_KEY')
API_URL = 'https://api.docurift.com/v1'

response = requests.get(
  f'{API_URL}/credits/balance',
  headers={'X-API-Key': API_KEY}
)

balance = response.json()
print(f"Available credits: {balance['data']['available']}")
print(f"Total credits: {balance['data']['total']}")
print(f"Used credits: {balance['data']['used']}")
javascript
const API_KEY = process.env.DOCURIFT_API_KEY;
const API_URL = 'https://api.docurift.com/v1';

const response = await fetch(`${API_URL}/credits/balance`, {
method: 'GET',
headers: {
  'X-API-Key': API_KEY
}
});

const balance = await response.json();
console.log('Available credits:', balance.data.available);
console.log('Total credits:', balance.data.total);
console.log('Used credits:', balance.data.used);

Response

response.json
{
"success": true,
"data": {
  "total": 550,
  "used": 127,
  "available": 423,
  "breakdown": {
    "free_tier": {
      "total": 50,
      "used": 50,
      "available": 0
    },
    "purchased": {
      "total": 500,
      "used": 77,
      "available": 423
    }
  },
  "lastUpdated": "2024-01-26T14:30:00Z"
}
}

Response Fields

ParameterTypeDescription
total
integerTotal credits ever allocated to your account
used
integerTotal credits consumed across all document processing
available
integerCredits remaining and available for use
breakdown
objectCredit breakdown by type (free_tier, purchased)
breakdown.free_tier
objectCredits from free tier allocation (50 pages on signup)
breakdown.purchased
objectCredits from purchases and top-ups
lastUpdated
stringISO 8601 timestamp of last balance update
💡

Credits Never Expire

Your credits never expire. Whether from the free tier or purchased, all credits remain available indefinitely until used.

Credit Types

Free Tier Credits

Every new account receives 50 free pages upon signup. These credits:

  • Are available immediately after account creation
  • Never expire
  • Are used first before purchased credits
  • Cannot be refunded or transferred

Purchased Credits

Credits purchased through the dashboard or API:

  • Are added to your balance immediately after payment
  • Never expire
  • Are used after free tier credits are exhausted
  • May be eligible for refunds (see refund policy)

Error Responses

error.json
{
"success": false,
"error": {
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
}

Error Codes

| Code | HTTP Status | Description | |------|-------------|-------------| | UNAUTHORIZED | 401 | Missing or invalid API key | | INVALID_API_KEY | 401 | API key is malformed or does not exist | | IP_BLOCKED | 403 | IP temporarily blocked due to failed attempts | | RATE_LIMIT_EXCEEDED | 429 | Too many requests, please retry later | | INTERNAL_ERROR | 500 | Server error, please retry or contact support |

Next Steps