> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vocobase.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Billing (₹)
> How Vocobase bills voice and chat usage in Indian Rupees
# Billing (₹)
Vocobase bills usage in **Indian Rupees (₹)**. Your partner account holds a ₹ balance that is drawn down as your agents handle voice calls or chat sessions.
**Unit change (May 2026):** Vocobase previously used an abstract "credits" unit. The wallet now stores rupees directly. The JSON field name `credits` on billing endpoints is **unchanged for backward compatibility**, but the numeric value now represents ₹ instead of credits.
## How voice calls are billed
Voice calls are billed in **15-second buckets** at a per-tier per-minute rate. Any call duration > 0 is rounded **up** to the next 15-second bucket.
### Per-tier default rates
| Tier | Default rate |
| ------------ | ------------ |
| **VA 1** | ₹3.60 / min |
| **VA 1 Pro** | ₹4.60 / min |
The tier of a call is determined by the **voice configuration** assigned to the agent. Agents without a voice configuration assigned default to **VA 1**.
### 15-second rounding examples
| Actual duration | Billed duration | Bucket count |
| --------------- | --------------- | ------------ |
| 1 second | 15 seconds | 1 |
| 14 seconds | 15 seconds | 1 |
| 19 seconds | 30 seconds | 2 |
| 1 minute 1 sec | 1 minute 15 sec | 5 |
### Cost examples (VA 1 default, ₹3.60/min)
| Actual duration | Cost |
| --------------- | ------ |
| 1 second | ₹0.90 |
| 30 seconds | ₹1.80 |
| 60 seconds | ₹3.60 |
| 1 minute 1 sec | ₹4.50 |
| 5 minutes | ₹18.00 |
A 0-second / never-connected call bills ₹0.
## Pricing overrides
Vocobase supports per-tier rate overrides at three scopes. At call end, the system walks the override chain and uses the first match for the call's tier; if no override matches, the default rate applies.
```
Agent → Project (Workspace) → Account → Default
```
This means you can negotiate a custom rate at the Account level, then optionally tighten or relax it for a specific Project or Agent. Overrides are managed by the Vocobase team — contact **[support@vocobase.com](mailto:support@vocobase.com)** to set up custom pricing.
***
## How chat is billed
Chat messages cost **₹0.035 per message**. Each user message and each agent response is counted.
| Chat messages | Cost |
| ---------------------------- | ------ |
| 10 messages (5 user + 5 bot) | ₹0.35 |
| 100 messages | ₹3.50 |
| 1,000 messages | ₹35.00 |
***
## When ₹ is deducted
₹ is deducted **automatically when a session ends** — not when the call starts:
1. A call is placed to the recipient
2. The agent handles the conversation
3. The call ends (hang up, timeout, or disconnect)
4. Vocobase rounds the duration up to the next 15-second bucket, resolves the tier and rate, and deducts ₹
5. A `session.completed` webhook fires with `credits_used` in the payload (note: value is in ₹)
```json theme={null}
{
"event": "session.completed",
"data": {
"session_id": "s1234567-abcd-1234-abcd-123456789012",
"duration_seconds": 127,
"credits_used": 8.10,
"...": "..."
}
}
```
The `credits_used` value of `8.10` above means **₹8.10** — the call was 127s actual → 135s billed (9 buckets) at the VA 1 default ₹3.60/min = `135 × 3.60 / 60 = ₹8.10` after rounding (worked example; check your transaction for exact rate at session time, since overrides may apply).
If a call fails to connect (e.g., no answer, busy), no ₹ is deducted.
***
## Initial balance
When your partner account is approved by the Vocobase team, an initial ₹ balance is assigned. The amount depends on your plan and agreement.
There is no self-service top-up via the API. To add more balance, contact the Vocobase team at **[support@vocobase.com](mailto:support@vocobase.com)**.
***
## Checking your balance
### Via the Dashboard
Log in to the [Vocobase Dashboard](https://app.vocobase.com) and navigate to **Settings**. Your current ₹ balance is displayed on the account overview.
### Via the API
#### Get current balance
```bash theme={null}
curl -X GET https://api.vocobase.com/api/v2/billing/balance \
-H "Authorization: Bearer rg_live_abc123def456ghi789jkl012"
```
```json theme={null}
{
"success": true,
"data": {
"credits": 1250.50
}
}
```
The value `1250.50` represents **₹1,250.50**.
#### Get transaction history
```bash theme={null}
curl -X GET "https://api.vocobase.com/api/v2/billing/transactions?limit=20&type=usage" \
-H "Authorization: Bearer rg_live_abc123def456ghi789jkl012"
```
| Parameter | Type | Description |
| ------------ | ------- | ------------------------------------------------------ |
| `limit` | integer | Max results (default 50, max 100) |
| `offset` | integer | Pagination offset (default 0) |
| `type` | string | Filter by type: `purchase`, `usage`, `refund`, `bonus` |
| `start_date` | string | ISO date, filter from this date |
| `end_date` | string | ISO date, filter until this date |
```json theme={null}
{
"success": true,
"data": {
"transactions": [
{
"id": "t1234567-abcd-1234-abcd-123456789012",
"amount": -8.55,
"type": "usage",
"description": "Voice session",
"created_at": "2026-05-15T10:30:00.000Z"
}
],
"total": 156,
"limit": 20,
"offset": 0
}
}
```
`amount` is in ₹. A USAGE row with `amount: -8.55` means **₹8.55 was deducted**. If you need a detailed billing audit for a call, contact Vocobase support with the `session_id`.
#### Get usage summary
```bash theme={null}
curl -X GET "https://api.vocobase.com/api/v2/billing/usage-summary?start_date=2026-05-01&end_date=2026-05-31" \
-H "Authorization: Bearer rg_live_abc123def456ghi789jkl012"
```
```json theme={null}
{
"success": true,
"data": {
"period": {
"start": "2026-05-01T00:00:00.000Z",
"end": "2026-05-31T23:59:59.000Z"
},
"summary": {
"usage": { "count": 142, "total": -1085.50 },
"purchase": { "count": 1, "total": 5000.00 }
},
"totals": {
"transaction_count": 143,
"credits_added": 5000.00,
"credits_used": 1085.50,
"net_change": 3914.50
}
}
}
```
All numeric values are in ₹.
***
## Insufficient balance
If your ₹ balance reaches zero, API calls that start new sessions will fail with:
```json theme={null}
{
"success": false,
"error": {
"code": "INSUFFICIENT_CREDITS",
"message": "Insufficient balance to start a new session"
}
}
```
Calls that are already in progress will not be interrupted. However, you will not be able to start new calls until balance is replenished.
***
## Monitoring usage
### Webhook tracking
The most reliable way to track usage is through webhooks. Every `session.completed` event includes the `credits_used` field (₹). Accumulate these values in your system to track spend in real time.
***
## Frequently asked questions
### Can I set a per-agent or per-workspace pricing?
Yes. Pricing overrides can be set at Account, Project (Workspace), or Agent scope. Overrides are managed by the Vocobase team — contact **[support@vocobase.com](mailto:support@vocobase.com)**.
### What happens if balance runs out mid-call?
Active calls are never interrupted. The deduction happens after the call ends, so your balance may temporarily go negative. Contact the Vocobase team promptly to replenish balance if this occurs.
### Can I get a refund for failed calls?
Calls that fail to connect (no answer, busy, provider error) do not consume ₹. If you believe ₹ was incorrectly deducted, contact **[support@vocobase.com](mailto:support@vocobase.com)** with the `session_id`.
### Why does the API return the field as `credits` if it's now in ₹?
To keep partner integrations working without changes. The JSON field name `credits` (and `credits_used`, `credits_added`) is kept verbatim; only its numeric meaning shifted from abstract credits to Indian Rupees in May 2026.
## Next steps
See the full session.completed payload including credits\_used.
Make your first API call and start using ₹.