Manage your organization’s billing account, including viewing your balance, adding funds, and configuring automatic reload settings.
Endpoints
| Method | Endpoint | Description |
|---|
GET | /v1/orgs/:org_id/billing | Get billing account |
PATCH | /v1/orgs/:org_id/billing | Update auto-reload settings |
POST | /v1/orgs/:org_id/billing/top-up | Add funds (create payment intent) |
POST | /v1/orgs/:org_id/billing/setup-intent | Set up payment method |
BillingAccount Object
{
"balance_cents": 5000,
"balance_usd": "50.00",
"currency": "usd",
"auto_reload_enabled": true,
"auto_reload_minimum_cents": 1000,
"auto_reload_amount_cents": 5000,
"has_payment_method": true
}
| Field | Type | Description |
|---|
balance_cents | integer | Current balance in cents |
balance_usd | string | Current balance formatted in USD (e.g. "50.00") |
currency | string | Always "usd" |
auto_reload_enabled | boolean | Whether auto-reload is active |
auto_reload_minimum_cents | integer | Balance threshold that triggers auto-reload |
auto_reload_amount_cents | integer | Amount added when auto-reload triggers |
has_payment_method | boolean | Whether a payment method is on file |
Get Billing Account
Retrieve the current billing account details for your organization.
curl https://api.thunderphone.com/v1/orgs/{org_id}/billing \
-H "Authorization: Token YOUR_API_TOKEN"
Update Auto-Reload Settings
Configure automatic balance top-ups when your balance falls below a threshold.
curl -X PATCH https://api.thunderphone.com/v1/orgs/{org_id}/billing \
-H "Authorization: Token YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"auto_reload_enabled": true,
"auto_reload_minimum_cents": 1000,
"auto_reload_amount_cents": 5000
}'
| Field | Type | Description |
|---|
auto_reload_enabled | boolean | Enable or disable auto-reload |
auto_reload_minimum_cents | integer | Balance threshold in cents (required when enabling) |
auto_reload_amount_cents | integer | Reload amount in cents, must be > 0 (required when enabling) |
When enabling auto-reload, both auto_reload_minimum_cents and auto_reload_amount_cents are required. A payment method must be on file — the request returns 422 if no payment method exists.
Add Funds (Top-Up)
Create a Stripe payment intent to add funds to your account balance.
curl -X POST https://api.thunderphone.com/v1/orgs/{org_id}/billing/top-up \
-H "Authorization: Token YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"amount_cents": 5000
}'
Request
| Field | Type | Required | Description |
|---|
amount_cents | integer | Yes | Amount to add in cents (minimum: 1) |
payment_method_id | string | No | Stripe payment method ID (uses default if omitted) |
Response (201)
{
"payment_intent_id": "pi_1234567890",
"status": "requires_confirmation",
"client_secret": "pi_1234567890_secret_abc123"
}
Use the client_secret with Stripe.js on the frontend to confirm the payment.
Set Up Payment Method
Create a Stripe setup intent to save a new payment method for future charges and auto-reload.
curl -X POST https://api.thunderphone.com/v1/orgs/{org_id}/billing/setup-intent \
-H "Authorization: Token YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'
Response (201)
{
"setup_intent_id": "seti_1234567890",
"client_secret": "seti_1234567890_secret_abc123",
"status": "requires_payment_method"
}
Use the client_secret with Stripe.js on the frontend to collect payment method details. 