Understand billing and usage for API integrations
Find out which billing information you can retrieve through API v1.1 and which records you need to download from the portal.
Choose the supported route
This table covers the published customer API v1.1. It does not describe bespoke commercial data feeds.
| Information or action | API v1.1 | Where to go |
|---|---|---|
| Current account balance and currency | GET /v1.1/organisation | See the balance example below. |
| Individual SMS charges or daily/monthly SMS totals | No usage-reporting endpoint | Export SMS history from the portal. |
| Voice call detail records, duration, and charges | No call-history endpoint | Export call history from the portal. |
| Invoices, payment history, or account ledger | No billing-history endpoint | Use portal Payments and Invoices. |
| SMS and voice usage rate cards, versions, and effective dates | No usage rate-card endpoint | Download the assigned cards from portal Rate Sheets. |
| Number purchase prices | GET /v1.1/catalogue and order preview | Follow Buy numbers with the API. |
| Assigned-number rental and next billing date | GET /v1.1/numbers | Follow Manage assigned numbers. |
| Immediate number disconnection | DELETE /v1.1/numbers/{sid} | Use the assigned-number SID beginning AN. |
| Change auto-renew or cancel at the end of a term | No scheduling or auto-renew operation | Immediate disconnection has different consequences; see the number-management guide. |
| Automatic card top-up settings or status | Not exposed | Use portal Billing Settings. |
Read your balance
The API v1.1 base URL is https://api.cloudnumbering.com/v1.1. Authenticate your request and store the access token in CLOUDNUMBERING_ACCESS_TOKEN.
curl --silent --show-error \
--header "Authorization: Bearer $CLOUDNUMBERING_ACCESS_TOKEN" \
'https://api.cloudnumbering.com/v1.1/organisation'Check success before reading result.balance and result.currency. The balance is expressed in major currency units: 1.2345 with currency GBP means £1.2345. See Get your organisation details for the complete response.
A balance is a current snapshot. Subtracting two balance readings does not identify an individual message or call charge, because other usage, rental charges, and top-ups can occur between requests.
Separate number prices from usage rates
Catalogue and available-number pricing cover number purchase and rental. They do not provide per-SMS or per-minute voice rates. rateCardSid and rateCardEntrySid on number orders identify the purchase rate card and selected number product.
Download SMS and voice cards from Rate Sheets. Keep the downloaded card and its Live From date for historical reconciliation. A card marked Live is currently assigned to your organisation; an older card can remain available after replacement.
Review charged usage
POST /v1.1/sms returns the message SID, with no charge amount. API v1.1 has no follow-up endpoint for that message's cost. SMS delivery receipts report delivery status, not charges. See Send SMS for acceptance and multipart charging rules.
For voice, API v1.1 has no outbound call-control or CDR billing endpoint. Review call charges in portal call history.
Use account history to export call and SMS records. The published documentation does not specify a guaranteed delay before a charge appears there.
Reconcile a reporting period
- Export the call and SMS history covering the period you need. Check the dates and rows included in each download; do not assume one table export contains the complete month.
- Download the relevant invoices and review payments using Payments and Invoices. Portal card top-ups generate invoices, including automatic card top-ups. These invoices record funding and must not be treated as monthly usage statements.
- Keep the applicable number, SMS, and voice rate cards alongside those records.
- Before automating imports, confirm the exports' matching identifiers, timezone, currency, and tax treatment for your reconciliation process. The API does not define a contract for these export fields.
Scheduled CSV or SFTP delivery and monthly usage statements are not specified by the published API contract. If your integration requires an automated feed, agree its availability and delivery contract with your account contact before depending on it.
Billing notifications
The published webhook documentation covers inbound SMS and outbound SMS delivery receipts. It provides no billing-event subscription for invoices, charged usage, settled payments, low balance, or upcoming, successful, or failed rental renewals.
Eligible organisations can configure low-balance alerts, delivered by email. Automatic card top-ups are a separate portal feature. Neither provides an API billing feed.
Confirm your rental terms
Follow Manage assigned numbers for automatic renewal, overdue numbers, and disconnection.
Before setting an end-user refund policy or promising a fixed future rental price, confirm mid-cycle refunds, proration, and renewal price-change terms against your agreement. Neither a number's current numberRental nor an order's rate-card identifiers establish those contractual terms.
Updated 8 days ago