Billing

Inspect your prepaid balance, top up by card, configure auto-reload thresholds and amounts, and list every transaction behind your organization

ThunderPhone is prepaid. Each organization carries a USD balance that decrements as calls are placed; if the balance reaches $0.00, inbound calls are rejected and outbound calls return 402 Payment Required. These endpoints let you query balance state, top up via Stripe, and configure automatic reloads.

Endpoints#

Billing account object#

{
  "balance_cents": 125000,
  "balance_usd": "1250.00",
  "currency": "usd",
  "auto_reload_enabled": true,
  "auto_reload_minimum_cents": 1000,
  "auto_reload_amount_cents": 5000,
  "auto_reload_monthly_limit_cents": null,
  "auto_reload_status": "ok",
  "auto_reload_next_retry_at": null,
  "auto_reload_failed_amount_cents": null,
  "auto_reload_failed_at": null,
  "auto_reload_consecutive_declines": null,
  "last_auto_reload": {
    "amount_cents": 5000,
    "created_at": "2026-09-20T14:02:11.482Z"
  },
  "auto_reload_month_spend_cents": 5000,
  "average_daily_spend_cents_7d": 390,
  "balance_runway_days": 320,
  "last_top_up": {
    "amount_cents": 5000,
    "created_at": "2026-09-20T14:02:11.482Z",
    "kind": "auto"
  },
  "has_payment_method": true,
  "has_ever_topped_up": true
}

Get billing account#

curl https://api.thunderphone.com/v1/billing \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Returns 200 OK with a Billing account object.

Update auto-reload#

Enable, disable, or reconfigure automatic balance reloads. A payment method must be on file (has_payment_method: true) before auto_reload_enabled can be set to true — otherwise the server returns 422 Unprocessable Entity with {"detail": "Auto-reload requires a default payment method. Create a setup intent first."}.

curl -X PATCH https://api.thunderphone.com/v1/billing \
  -H "Authorization: Token YOUR_SESSION_TOKEN" \
  -H "X-ThunderPhone-Org: 42" \
  -H "Content-Type: application/json" \
  -d '{
    "auto_reload_enabled": true,
    "auto_reload_minimum_cents": 1000,
    "auto_reload_amount_cents": 5000,
    "auto_reload_monthly_limit_cents": 50000
  }'

curl -X PATCH https://api.thunderphone.com/v1/billing \
  -H "Authorization: Token YOUR_SESSION_TOKEN" \
  -H "X-ThunderPhone-Org: 42" \
  -H "Content-Type: application/json" \
  -d '{"auto_reload_enabled": false}'

Returns 200 OK with the updated Billing account object.

Top up balance#

Create a one-time charge to increase your balance. Uses the default payment method unless payment_method_id is supplied.

curl -X POST https://api.thunderphone.com/v1/billing/top-up \
  -H "Authorization: Token YOUR_SESSION_TOKEN" \
  -H "X-ThunderPhone-Org: 42" \
  -H "Content-Type: application/json" \
  -d '{"amount_cents": 10000}'

result = requests.post(
    "https://api.thunderphone.com/v1/billing/top-up",
    headers={"Authorization": "Token YOUR_SESSION_TOKEN", "X-ThunderPhone-Org": "42"},
    json={"amount_cents": 10000},
).json()

Returns 201 Created:

{
  "payment_intent_id": "pi_abc123",
  "status":            "succeeded",
  "client_secret":     "pi_abc123_secret_..."
}

When status === "succeeded" the balance is credited synchronously from the request. When status === "requires_action", complete the 3DS flow client-side and wait for the payment_intent.succeeded webhook — then poll GET /v1/billing to observe the credit.

Errors#

Validation problems (e.g. a missing or non-positive amount_cents) return 400 with a standard DRF field-error body:

{ "amount_cents": ["Ensure this value is greater than or equal to 1."] }

Payment failures return a structured error body with a machine-readable code, plus message/detail, a retryable hint, and a next_action your client can act on:

{
  "code": "payment_authentication_required",
  "message": "This card requires additional verification. Please retry and complete authentication when prompted.",
  "detail": "This card requires additional verification. Please retry and complete authentication when prompted.",
  "retryable": true,
  "next_action": "authenticate_payment"
}

These same coded errors are returned by the other billing write endpoints when they hit Stripe (/setup-intent, /default-payment-method).

Add / save a payment method#

Two-step flow: create a SetupIntent, confirm it client-side, then set the resulting payment-method id as the org's default.

1. Create a SetupIntent#

curl -X POST https://api.thunderphone.com/v1/billing/setup-intent \
  -H "Authorization: Token YOUR_SESSION_TOKEN" \
  -H "X-ThunderPhone-Org: 42"

{
  "setup_intent_id": "seti_abc123",
  "client_secret": "seti_abc123_secret_...",
  "status": "requires_payment_method"
}

2. Confirm client-side with Stripe.js#

See the Stripe documentation for stripe.confirmCardSetup(). On success you receive a payment_method id.

3. Mark the payment method as default#

curl -X POST https://api.thunderphone.com/v1/billing/default-payment-method \
  -H "Authorization: Token YOUR_SESSION_TOKEN" \
  -H "X-ThunderPhone-Org: 42" \
  -H "Content-Type: application/json" \
  -d '{"payment_method_id": "pm_abc123"}'

Returns 200 OK with the updated Billing account object; has_payment_method is now true.

To switch the default to a card that is already saved, call this endpoint with that card's id from List saved cards.

List saved cards#

Returns every card saved on the organization, the default first and the rest newest first. Top-ups and auto-reloads charge the default card. Requires the admin or owner role.

curl https://api.thunderphone.com/v1/billing/payment-methods \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

{
  "payment_methods": [
    {
      "id": "pm_abc123",
      "brand": "visa",
      "last4": "4242",
      "exp_month": 4,
      "exp_year": 2031,
      "is_default": true
    },
    {
      "id": "pm_def456",
      "brand": "mastercard",
      "last4": "4444",
      "exp_month": 12,
      "exp_year": 2030,
      "is_default": false
    }
  ]
}

An organization that has never saved a card gets an empty list.

Remove a saved card#

Detaches the card from the organization. This cannot be undone; save the card again to use it later. Requires the admin or owner role.

curl -X DELETE https://api.thunderphone.com/v1/billing/payment-methods/pm_def456 \
  -H "Authorization: Token YOUR_SESSION_TOKEN" \
  -H "X-ThunderPhone-Org: 42"

Returns 204 No Content.

List transactions#

Returns every ledger entry on the account — top-ups, per-call usage, monthly number fees, and manual adjustments — newest first.

curl 'https://api.thunderphone.com/v1/billing/transactions?limit=200' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

txns = requests.get(
    "https://api.thunderphone.com/v1/billing/transactions",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    params={"limit": 200},
).json()

Query parameters#

The response is a plain JSON array of transaction objects (no {results, total} envelope). Page forward by increasing offset until you receive fewer rows than limit.

Transaction object#

{
  "id": 3421,
  "kind": "call_usage",
  "description": "Call billing: 2 minutes × $0.02",
  "amount_cents": -4,
  "amount_usd": "-0.04",
  "call_id": 987654321,
  "phone_number_id": 201,
  "phone_number_value": "+15551234567",
  "metadata": {},
  "has_receipt": false,
  "created_at": "2026-04-20T18:25:06.201Z"
}

Get a receipt#

Returns a link to the payment receipt for a top-up or automatic top-up, for rows where has_receipt is true. The receipt is hosted by our payment processor, Stripe, and shows the amount, date, and card charged. Owners and admins can fetch it; other members get 403, because the receipt shows the card brand and last four digits.

curl https://api.thunderphone.com/v1/billing/transactions/3398/receipt \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

receipt = requests.get(
    "https://api.thunderphone.com/v1/billing/transactions/3398/receipt",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
).json()
print(receipt["receipt_url"])

{
  "receipt_url": "https://pay.stripe.com/receipts/payment/..."
}

Stripe webhook#

ThunderPhone receives Stripe webhooks at /v1/stripe/webhook internally — you don't interact with this endpoint directly. It processes payment_intent.succeeded, payment_intent.payment_failed, and setup_intent.succeeded events to update balances and mark payment methods ready.

Related#