---
title: "Credits"
description: "Credit system for API usage — allocations, consumption tracking, and balance management"
canonical: "https://docs.ainative.studio/docs/billing/credits"
last-updated: "2026-10-22T17:48:46.689Z"
---

# Credits

Source: https://docs.ainative.studio/docs/billing/credits

> Credit system for API usage — allocations, consumption tracking, and balance management

## Credits

Credits are the primary unit of platform consumption. This page covers how to check your balance, view transaction history, browse credit packages, create a Stripe payment intent for purchases, and configure auto-refill.

**Base URL:** `https://api.ainative.studio`

---

## Get Credit Balance

<span className="badge badge--get">GET</span> `/api/v1/public/credits/balance`

Returns the current credit balance for the authenticated user. Balance is computed by summing usage across `ai_usage_logs`, `api_usage_logs`, `chat_completion_usage`, and `credit_transactions`.

**Auth required.**

```bash
curl https://api.ainative.studio/api/v1/public/credits/balance \
  -H "Authorization: Bearer <your_api_key>"
```

```python
import httpx

resp = httpx.get(
    "https://api.ainative.studio/api/v1/public/credits/balance",
    headers={"Authorization": "Bearer <your_api_key>"},
)
balance = resp.json()
print(f"Remaining: {balance['remaining_credits']} / {balance['total_credits']}")
```

**Response**

```json
{
  "total_credits": 50000,
  "used_credits": 12340.5,
  "remaining_credits": 37659.5,
  "plan": "pro",
  "period_start": "2026-04-01T00:00:00Z",
  "period_end": "2026-04-30T23:59:59Z",
  "usage_percentage": 24.68
}
```

| Field | Description |
|-------|-------------|
| `total_credits` | Total credits available this period (plan allowance + purchased) |
| `used_credits` | Credits consumed since `period_start` |
| `remaining_credits` | `total_credits - used_credits` (floored at 0) |
| `plan` | Current plan tier (`free`, `basic`, `pro`, `enterprise`) |
| `period_start` | Start of current billing period |
| `period_end` | End of current billing period (`null` for free tier) |
| `usage_percentage` | Percentage of credits consumed |

---

## Transaction History

<span className="badge badge--get">GET</span> `/api/v1/public/credits/transactions`

Paginated history of credit usage events from `ai_usage_logs`.

**Auth required.**

**Query parameters**

| Param | Type | Default | Description |
|-------|------|---------|-------------|
| `skip` | integer | 0 | Records to skip |
| `limit` | integer | 50 | Max records (1–50) |

```bash
curl "https://api.ainative.studio/api/v1/public/credits/transactions?skip=0&limit=20" \
  -H "Authorization: Bearer <your_api_key>"
```

**Response**

```json
{
  "success": true,
  "data": {
    "transactions": [
      {
        "id": "txn-uuid",
        "type": "usage",
        "amount": -4.5,
        "description": "chat_completion using gpt-4o",
        "tokens_processed": 1500,
        "processing_time_ms": 823,
        "created_at": "2026-04-25T09:30:00Z",
        "session_id": "session-uuid"
      }
    ],
    "total": 843,
    "skip": 0,
    "limit": 20,
    "has_more": true
  }
}
```

Note: `amount` is negative for usage deductions.

---

## Current Period Usage

<span className="badge badge--get">GET</span> `/api/v1/public/credits/usage/current`

Aggregated usage statistics for the current billing period, broken down by operation type and day.

**Auth required.**

```bash
curl https://api.ainative.studio/api/v1/public/credits/usage/current \
  -H "Authorization: Bearer <your_api_key>"
```

**Response**

```json
{
  "success": true,
  "data": {
    "period_start": "2026-04-01T00:00:00Z",
    "period_end": "2026-04-30T23:59:59Z",
    "summary": {
      "total_requests": 1204,
      "total_credits_used": 12340.5,
      "total_tokens_processed": 4100000,
      "unique_sessions": 38,
      "active_days": 22
    },
    "by_operation_type": [
      {
        "operation_type": "chat_completion",
        "request_count": 980,
        "credits_used": 10200.0
      },
      {
        "operation_type": "embedding",
        "request_count": 224,
        "credits_used": 2140.5
      }
    ],
    "daily_usage": [
      {
        "date": "2026-04-25",
        "request_count": 54,
        "credits_used": 540.0
      }
    ]
  }
}
```

---

## Credit Packages

<span className="badge badge--get">GET</span> `/api/v1/public/credits/packages`

List available credit packages that can be purchased. Packages are loaded from the `credit_packages` database table; the response below shows the fallback list returned when the database is unavailable.

**Auth required.**

```bash
curl https://api.ainative.studio/api/v1/public/credits/packages \
  -H "Authorization: Bearer <your_api_key>"
```

**Response**

```json
{
  "success": true,
  "data": {
    "packages": [
      {
        "id": "credits_250",
        "name": "250 Credits",
        "credits": 250,
        "price": 10.00,
        "currency": "USD",
        "popular": false,
        "description": "Starter pack for light usage",
        "features": ["250 prompt credits", "Works with all AI models", "Never expires", "Instant activation"]
      },
      {
        "id": "credits_1000",
        "name": "1,000 Credits",
        "credits": 1000,
        "price": 40.00,
        "currency": "USD",
        "popular": true,
        "description": "Best value for regular users",
        "features": ["1,000 prompt credits", "Works with all AI models", "Never expires", "Instant activation", "Priority processing"]
      },
      {
        "id": "credits_5000",
        "name": "5,000 Credits",
        "credits": 5000,
        "price": 175.00,
        "currency": "USD",
        "popular": false,
        "description": "High-volume pack for power users",
        "features": ["5,000 prompt credits", "Works with all AI models", "Never expires", "Instant activation", "Priority processing"]
      }
    ]
  }
}
```

---

## Create Payment Intent for Credits

<span className="badge badge--post">POST</span> `/api/v1/public/credits/payment-intent`

Create a Stripe Payment Intent for purchasing a credit package. Returns a `client_secret` your frontend uses with Stripe.js to complete payment. Credits are added after the webhook confirms payment success.

**Auth required.**

**Request body**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `package_id` | string | Yes | Package ID from `GET /credits/packages` |
| `amount` | number | Yes | Amount in USD (must be > 0) |

```bash
curl -X POST https://api.ainative.studio/api/v1/public/credits/payment-intent \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"package_id": "credits_1000", "amount": 40.00}'
```

```python
import httpx

resp = httpx.post(
    "https://api.ainative.studio/api/v1/public/credits/payment-intent",
    headers={"Authorization": "Bearer <your_api_key>"},
    json={"package_id": "credits_1000", "amount": 40.00},
)
data = resp.json()["data"]
client_secret = data["client_secret"]
## Pass client_secret to Stripe.js on the frontend
```

**Response**

```json
{
  "success": true,
  "data": {
    "payment_intent_id": "pi_xxx",
    "client_secret": "pi_xxx_secret_yyy",
    "amount": 40.00,
    "currency": "USD",
    "package_id": "credits_1000"
  },
  "message": "Payment intent created successfully"
}
```

:::info Note
`POST /api/v1/public/credits/purchase` is disabled (`501 Not Implemented`). Use the payment intent flow above instead.
:::

---

## Auto-Refill Settings

Auto-refill automatically triggers a credit purchase when your balance drops below a configured threshold.

### Get Auto-Refill Settings

<span className="badge badge--get">GET</span> `/api/v1/public/credits/auto-refill-settings`

**Auth required.**

```bash
curl https://api.ainative.studio/api/v1/public/credits/auto-refill-settings \
  -H "Authorization: Bearer <your_api_key>"
```

**Response**

```json
{
  "success": true,
  "data": {
    "enabled": false,
    "threshold": 100,
    "amount": 1000,
    "payment_method_id": null
  }
}
```

| Field | Description |
|-------|-------------|
| `enabled` | Whether auto-refill is active |
| `threshold` | Credit level that triggers a refill |
| `amount` | Credits to purchase when triggered |
| `payment_method_id` | Stripe payment method to charge |

---

### Update Auto-Refill Settings

<span className="badge badge--put">PUT</span> `/api/v1/public/credits/auto-refill-settings`

**Auth required.**

**Request body**

| Field | Type | Description |
|-------|------|-------------|
| `enabled` | boolean | Enable or disable auto-refill |
| `threshold` | integer | Balance threshold (must be ≥ 0) |
| `amount` | integer | Credits to refill (must be > 0) |
| `payment_method_id` | string | Stripe payment method ID |

```bash
curl -X PUT https://api.ainative.studio/api/v1/public/credits/auto-refill-settings \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "threshold": 500,
    "amount": 1000,
    "payment_method_id": "pm_xxx"
  }'
```

**Response**

```json
{
  "success": true,
  "data": {
    "enabled": true,
    "threshold": 500,
    "amount": 1000,
    "payment_method_id": "pm_xxx"
  },
  "message": "Auto-refill settings updated successfully"
}
```

---

## Active API Keys Count

<span className="badge badge--get">GET</span> `/api/v1/public/credits/api-keys/count`

Returns the count of active API keys for the current user. Useful for billing dashboards.

**Auth required.**

```bash
curl https://api.ainative.studio/api/v1/public/credits/api-keys/count \
  -H "Authorization: Bearer <your_api_key>"
```

**Response**

```json
{
  "success": true,
  "data": {
    "active_api_keys": 3,
    "user_email": "user@example.com"
  }
}
```