Get billing status

GET

https://api.getdial.ai/api/v1/billing

GET

/api/v1/billing

curl https://api.getdial.ai/api/v1/billing \
     -H "Authorization: Bearer <token>"

{
  "balanceCents": 1500,
  "numbersReleaseAt": "2026-06-29T00:00:00.000Z",
  "subscription": {
    "periodStart": "2024-01-15T09:30:00Z",
    "periodEnd": "2024-01-15T09:30:00Z",
    "quantity": 1,
    "interval": "monthly",
    "cancelAtPeriodEnd": true
  },
  "numbers": [
    {
      "id": "string",
      "number": "+14155550123",
      "nickname": "Support line",
      "mode": "PAYG"
    }
  ],
  "deposits": [
    {
      "createdAt": "2024-01-15T09:30:00Z",
      "amountCents": 1,
      "kind": "card",
      "invoiceId": "in_1QabcdEFghij"
    }
  ],
  "coupons": [
    {
      "code": "EVENT_CODE",
      "amountCents": 10000,
      "redeemedAt": "2024-01-15T09:30:00Z",
      "expiresAt": "2024-01-15T09:30:00Z"
    }
  ],
  "pricing": {
    "monthlyCents": 1,
    "annualCents": 1
  },
  "paymentMethods": [
    {
      "id": "string",
      "type": "card",
      "brand": "visa",
      "last4": "4242",
      "expMonth": 4,
      "expYear": 2027,
      "email": "string",
      "isDefault": true
    }
  ]
}

Returns the account’s credit-wallet balance, the current subscription (if any), each phone number’s billing mode (PAYG or FIXED), and recent usage.

Authentication

AuthorizationBearer

Your Dial API key, sent as Authorization: Bearer sk_live_...

Response

Billing status.

balanceCentsintegerOptional

Credit-wallet balance in USD cents. May be negative.

numbersReleaseAtdatetime or nullOptional

When all of the account’s numbers will be released for non-payment, or null when nothing is at risk. Non-null only for a pay-as-you-go account whose balance is negative: it’s the end of the 30-day grace period (measured from when the balance first went negative). Topping the balance back to zero or above clears it. Subscription-covered accounts are never at risk, so this is always null for them.

subscriptionobject or nullOptional

The current subscription, or null when the account is pay-as-you-go.

numberslist of objectsOptional

depositslist of objectsOptional

Recent credits added to the wallet, most recent first.

couponslist of objectsOptional

Coupon codes this account redeemed, most recent first. Empty when none.

pricingobjectOptional

Per-number subscription unit prices (USD cents), read from Stripe (the source of truth). Stripe is a dependency of this endpoint.

paymentMethodslist of objectsOptional

Saved payment methods on the account’s Stripe customer (all reusable types — card, Link, …), used for top-ups and subscription billing. Empty until one is added. Read live from Stripe, with the default first.

Errors

401

Unauthorized Error