Usage & Billing

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

Pricing Tiers

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.

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).

Check Usage

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

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

Response:

1
{
2
  "workspace_id": "ws_abc123",
3
  "voice_minutes": 127,
4
  "whatsapp_conversations": 843,
5
  "sms_messages": 1562,
6
  "total_cost_minor": 3850000,
7
  "currency": "NGN"
8
}

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:

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

Response:

1
{
2
  "balance_kobo": 7500000,
3
  "currency": "NGN"
4
}

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:

$
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:

1
{
2
  "authorization_url": "https://checkout.paystack.com/abc123xyz",
3
  "reference": "vb_ref_k7Tz9mWvXp3nR",
4
  "amount_kobo": 5000000,
5
  "currency": "NGN"
6
}

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.

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

1
{
2
  "id": "sub_abc123",
3
  "workspace_id": "ws_abc123",
4
  "plan": "builder",
5
  "status": "active",
6
  "period_start": "2026-04-01T00:00:00Z",
7
  "period_end": "2026-04-30T23:59:59Z",
8
  "created_at": "2026-04-01T00:00:00Z",
9
  "updated_at": "2026-04-01T00:00:00Z"
10
}

To retrieve remaining quota for the current period:

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

1
{
2
  "voice_minutes_remaining": 382,
3
  "sms_remaining": 4210,
4
  "whatsapp_remaining": 1875,
5
  "numbers_included": 3,
6
  "numbers_active": 2,
7
  "period_end": "2026-04-30T23:59:59Z"
8
}

Switch Plans

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

$
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:

1
{
2
  "subscription": {
3
    "plan": "builder",
4
    "period_start": "2026-04-01T00:00:00Z",
5
    "period_end": "2026-04-30T23:59:59Z"
6
  },
7
  "proration": {
8
    "refund_minor": 580645,
9
    "charge_minor": 1290322,
10
    "net_minor": 709677
11
  },
12
  "quota_after": {
13
    "voice_minutes_remaining": 310,
14
    "sms_remaining": 3125,
15
    "whatsapp_remaining": 1250,
16
    "numbers_included": 3
17
  }
18
}

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 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 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. 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.

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

1
{
2
  "workspace_id": "ws_abc123",
3
  "voice_minutes": 12,
4
  "whatsapp_conversations": 5,
5
  "sms_messages": 34,
6
  "total_cost_minor": 0,
7
  "currency": "NGN"
8
}