Automate External Billing with the API
Use the External Billing API to read subscriptions, payment requests and usage, and mark payments as paid from your own billing or accounting system.
Written By voiceaiwrapper
Last updated 26 days ago
If you take client payments through your own system (a payment processor, an invoicing tool or your accounting software), the External Billing API lets that system talk to VoiceAIWrapper directly. The most common use: when a client's payment clears on your side, your system marks the matching payment request as paid, and the client's access and campaigns come back without anyone opening the webapp.
Available on: plans that include External billing API. Without it, every request returns a 403 error saying your plan doesn't include External Billing API access.
When to use the API
Use it when you want to:
- Record payments automatically. Mark a payment request as paid, with your own payment reference, as soon as the money arrives.
- Keep your records in sync. Pull subscriptions and payment requests into your CRM, accounting or invoicing tool, so you can send your own invoices for each request.
- Track usage. Read each client's included minutes used, usage-pack balance and billable minutes.
The API doesn't create plans, assign them, start or cancel subscriptions, or apply usage packs. Do those in the webapp; see External Billing: Plans, Usage Packs and Payment Requests.
Before you start
- External billing set up, with at least one client subscribed to a plan.
- An API key. Only organization Owners and Admins can create one, and creating keys needs the Platform API plan feature. See Create and Manage API Keys.
Step 1: Create an API key
- Open Settings and go to the API keys section.
- Click New key, give it a recognizable name (for example, "Billing sync") and click Generate key.
- Copy the key and store it in your billing system's secure settings.
Treat the key like a password. Anyone with it can read your clients' billing data and mark their payments as paid. If a key leaks, delete it in Settings β API keys and create a new one.
Step 2: Call the API
Send every request with your key as a Bearer token:
Authorization: Bearer YOUR_API_KEY
The API has six endpoints, all under /api/v2/external-billing/ on the VoiceAIWrapper API host:
List endpoints return 20 results per page by default. Use page and page_size (up to 100) to page through them.
Mark a payment as paid
Send a PATCH to the payment request's update path with the new status. Include your own payment ID so you can match it later:
{
"status": "PAID",
"external_payment_id": "your-payment-reference"
}
This works exactly like choosing Paid in the webapp. If the client was overdue and this clears their last unpaid subscription request, their subscription becomes active again, their portal opens and campaigns paused for billing resume. See Overdue Payments and Grace Periods (External Billing).
Valid statuses are PENDING, PAID, FAILED, CANCELED and OVERDUE. Only PAID restores access; the others just change the status.
IDs
The API only accepts the IDs it returns itself (the same IDs the webapp uses), not shortened or database IDs. To get a payment request's ID from the webapp, open the client's Billing β Payment Requests tab and click the copy icon next to Request ID: on the row. Otherwise, list subscriptions or payment requests first and take the IDs from the response.
Full developer reference
For request and response examples, every field and all filters, click Manage via API at the top of Billing Configuration β External Billing, or the Manage via API tab on an External billing client's Billing tab. It opens the External Billing API reference in a new tab.
Troubleshooting
I get a 401 or 404 error about the API key.
I get a 401 or 404 error about the API key.
Check the header is exactly Authorization: Bearer YOUR_API_KEY, with a space after Bearer. "API key not found" means the key is wrong or was deleted.
I get a 403 error.
I get a 403 error.
Either the key is turned off in Settings β API keys ("API key is disabled"), or your plan doesn't include External Billing API access. See A Feature Is Locked or Asks Me to Upgrade.
I get a 400 error about an ID.
I get a 400 error about an ID.
The ID isn't in the format the API expects. Use the IDs from API responses, or copy the Request ID: from the client's Payment Requests tab.
I get "Rate limit exceeded" (429).
I get "Rate limit exceeded" (429).
Each endpoint accepts up to 100 requests per minute per API key. Wait a minute and retry, and space out bulk syncs. See API Reference Overview and Rate Limits.
Related articles
Was this helpful?
More in Billing Your Clients
Ways to Bill Your Clients: Stripe or External BillingConnect Your Stripe AccountTax Settings for Client BillingChoose a Pricing ModelStill need help? Share an idea