> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.voicebip.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.voicebip.com/_mcp/server.

# Usage & Billing

> Monitor usage, understand pricing tiers, and manage billing with Paystack (NGN).

Track voice minutes, WhatsApp conversations, and SMS messages across your workspace. Pay in Naira via Paystack.

## Pricing Tiers

|                                     | Starter       | Builder       | Scale          | Pay As You Go         |
| ----------------------------------- | ------------- | ------------- | -------------- | --------------------- |
| **Monthly price**                   | Free          | NGN 25,000/mo | NGN 100,000/mo | ₦0 (no base fee)      |
| **Voice minutes included**          | 100           | 1,000         | 5,000          | None — billed per use |
| **WhatsApp conversations included** | 50            | 500           | 2,500          | None — billed per use |
| **SMS messages included**           | 100           | 1,000         | 5,000          | None — billed per use |
| **Agents**                          | 2             | 10            | Unlimited      | Unlimited             |
| **Recording add-on**                | Not available | ₦10,000/mo    | Included       | ₦15,000/mo            |

Starter, Builder, and Scale are subscription tiers billed monthly. **Pay As You Go (PAYG)** has no monthly commitment — you pay only for what you use at flat per-unit rates. PAYG is ideal for low-volume or irregular workloads where a monthly subscription is not cost-effective.

All tiers include full API access, webhook delivery, and dashboard analytics.

## Overage Rates

When you exceed your tier's included usage, overage is billed per unit. PAYG has no included quota — every unit is billed at the flat rate from the first use.

| Channel                | Starter          | Builder          | Scale            | PAYG (flat rate)    |
| ---------------------- | ---------------- | ---------------- | ---------------- | ------------------- |
| Voice (BYOM / webhook) | ₦50/min          | ₦40/min          | ₦30/min          | ₦70/min             |
| Voice (hosted AI)      | ₦80/min          | ₦65/min          | ₦50/min          | ₦100/min            |
| WhatsApp               | ₦20/conversation | ₦15/conversation | ₦10/conversation | ₦25/conversation    |
| SMS                    | ₦15/message      | ₦12/message      | ₦8/message       | ₦20/message         |
| Phone number           | —                | —                | —                | ₦6,000/number/month |

Voice rates differ by AI mode: BYOM (your webhook handles the AI) is billed at a lower rate than hosted AI mode (Voicebip runs the AI on your behalf).

> **Note**
>
> SMS overage is billed per segment. A 200-character GSM-7 message counts as 2 segments.

## Check Usage

Retrieve your current billing period usage with `GET /v1/usage`:

```bash
curl "https://api.voicebip.com/v1/usage" \
  -H "Authorization: Bearer pk_live_your_key"
```

Response:

```json
{
  "workspace_id": "ws_abc123",
  "voice_minutes": 127,
  "whatsapp_conversations": 843,
  "sms_messages": 1562,
  "total_cost_minor": 3850000,
  "currency": "NGN"
}
```

The `total_cost_minor` field is in kobo (100 kobo = 1 NGN). Divide by 100 to get the amount in the major unit — in this example, NGN 38,500.00.

## Check Balance

Retrieve your current prepaid balance with `GET /v1/billing/balance`:

```bash
curl "https://api.voicebip.com/v1/billing/balance" \
  -H "Authorization: Bearer pk_live_your_key"
```

Response:

```json
{
  "balance_kobo": 7500000,
  "currency": "NGN"
}
```

A `balance_kobo` of `7500000` equals NGN 75,000.00.

## Top Up Balance

Add funds to your account with `POST /v1/billing/checkout`. The API returns a Paystack authorization URL where the user completes payment:

```bash
curl -X POST "https://api.voicebip.com/v1/billing/checkout" \
  -H "Authorization: Bearer pk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dev@example.com",
    "amount_kobo": 5000000
  }'
```

Response:

```json
{
  "authorization_url": "https://checkout.paystack.com/abc123xyz",
  "reference": "vb_ref_k7Tz9mWvXp3nR",
  "amount_kobo": 5000000,
  "currency": "NGN"
}
```

Redirect the user to the `authorization_url` to complete the payment on Paystack. Once the payment succeeds, Paystack sends a webhook to Voicebip and the balance is credited automatically.

An `amount_kobo` of `5000000` equals NGN 50,000.00.

## Check Your Current Plan

Retrieve your active subscription and period dates with `GET /v1/workspace/subscription`. For remaining quota, use `GET /v1/billing/quota`.

```bash
curl "https://api.voicebip.com/v1/workspace/subscription" \
  -H "Authorization: Bearer pk_live_your_key"
```

```json
{
  "id": "sub_abc123",
  "workspace_id": "ws_abc123",
  "plan": "builder",
  "status": "active",
  "period_start": "2026-04-01T00:00:00Z",
  "period_end": "2026-04-30T23:59:59Z",
  "created_at": "2026-04-01T00:00:00Z",
  "updated_at": "2026-04-01T00:00:00Z"
}
```

To retrieve remaining quota for the current period:

```bash
curl "https://api.voicebip.com/v1/billing/quota" \
  -H "Authorization: Bearer pk_live_your_key"
```

```json
{
  "voice_minutes_remaining": 382,
  "sms_remaining": 4210,
  "whatsapp_remaining": 1875,
  "numbers_included": 3,
  "numbers_active": 2,
  "period_end": "2026-04-30T23:59:59Z"
}
```

## Switch Plans

Change your plan mid-period with `PATCH /v1/workspace/subscription`:

```bash
curl -X PATCH "https://api.voicebip.com/v1/workspace/subscription" \
  -H "Authorization: Bearer pk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "plan": "builder" }'
```

Response:

```json
{
  "subscription": {
    "plan": "builder",
    "period_start": "2026-04-01T00:00:00Z",
    "period_end": "2026-04-30T23:59:59Z"
  },
  "proration": {
    "refund_minor": 580645,
    "charge_minor": 1290322,
    "net_minor": 709677
  },
  "quota_after": {
    "voice_minutes_remaining": 310,
    "sms_remaining": 3125,
    "whatsapp_remaining": 1250,
    "numbers_included": 3
  }
}
```

The `proration` object shows the exact amounts debited and credited for the remaining days in your billing period. The net charge is deducted from your balance immediately.

**Limits and rules:**

* Plan changes are limited to **once every 24 hours** per workspace. A second request within that window returns `429 TIER_SWITCH_TOO_FREQUENT`.
* Upgrading to a higher plan requires enough balance to cover the prorated charge. If your balance is insufficient, the request returns `402 INSUFFICIENT_BALANCE` — top up first.
* Included quota for the new plan is prorated by the days remaining in your billing period. You receive a fraction of the monthly quota, not the full amount, so switching plans repeatedly within one period does not yield extra free minutes.
* Unused quota from your old plan carries over unchanged.
* **PAYG workspaces cannot switch plans via this endpoint** — the request returns `422 TIER_SWITCH_UNSUPPORTED`. Contact [support@voicebip.com](mailto:support@voicebip.com) to move a PAYG workspace onto a subscription tier.

## Balance Enforcement

Voicebip billing uses a **fail-closed balance model**. When your balance reaches zero:

1. All voice calls are rejected at the SIP layer with a 402 response.
2. All SMS and WhatsApp sends return `402 WORKSPACE_BLOCKED`.
3. Inbound calls from MNOs are immediately disconnected.

As soon as a top-up clears (Paystack webhook delivery is typically under 5 seconds), the block is lifted automatically. No manual intervention required.

## Low Balance Alerts

When your balance drops below your low-balance threshold, Voicebip sends one email alert per 24-hour window to the workspace owner. There is no API to configure the threshold today — contact [support@voicebip.com](mailto:support@voicebip.com) if you need a custom threshold.

You can poll your balance programmatically and build your own alerting on top of `GET /v1/billing/balance`.

## International Billing

For developers outside Nigeria who require USD billing, contact [sales@voicebip.com](mailto:sales@voicebip.com). USD top-ups are handled as bespoke arrangements; the self-serve `POST /v1/billing/checkout` endpoint is NGN / Paystack only.

## Sandbox Mode

API keys with the `pk_test_` prefix operate in sandbox mode:

* All API endpoints work identically to production
* Usage is tracked in the dashboard and via `GET /v1/usage`
* **No charges are incurred** — all billing amounts are NGN 0
* Voice calls, SMS, and WhatsApp messages are simulated via synthetic NATS events (no real MNO or Meta traffic)

Use sandbox mode during development and integration testing. Switch to a `pk_live_` key when you are ready for production.

```bash
# Check sandbox usage — works the same, billing is zero
curl "https://api.voicebip.com/v1/usage" \
  -H "Authorization: Bearer pk_test_your_key"
```

```json
{
  "workspace_id": "ws_abc123",
  "voice_minutes": 12,
  "whatsapp_conversations": 5,
  "sms_messages": 34,
  "total_cost_minor": 0,
  "currency": "NGN"
}
```