---
title: "Get billing status"
method: GET
path: "/api/v1/billing"
tags: ["billing"]
---

# Get billing status

`GET /api/v1/billing`

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

## Headers

- `Authorization` string, required

## Response `200`

Billing status.

- Billing — Account billing status (GET /api/v1/billing).
  - `balanceCents` integer — Credit-wallet balance in USD cents. May be negative.
  - `numbersReleaseAt` string, date-time, nullable — 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.
  - `subscription` BillingSubscription — The current subscription, or null when the account is pay-as-you-go.
    - `periodStart` string, date-time
    - `periodEnd` string, date-time
    - `quantity` integer — How many of your phone numbers this subscription covers (one unit each). `0` while you hold none — the subscription stays active and still bills for **one** number (its minimum), so the amount charged is `max(quantity, 1)` × the unit price, and the next number you provision is free.
    - `interval` 'monthly' | 'annual'
    - `cancelAtPeriodEnd` boolean — True when the subscription is scheduled to cancel at periodEnd (coverage stays until then, then the account reverts to PAYG). Read live from Stripe, the source of truth.
  - `numbers` BillingNumbersItems[]
    - `id` string
    - `number` string
    - `nickname` string, nullable — User-assigned label for the number, or null if unset.
    - `mode` 'PAYG' | 'FIXED' — PAYG bills the wallet; FIXED is covered by a subscription.
  - `deposits` BillingDepositsItems[] — Recent credits added to the wallet, most recent first.
    - `createdAt` string, date-time
    - `amountCents` integer — Amount credited, in USD cents (positive).
    - `kind` 'card' | 'welcome' | 'manual' — `card` — paid Stripe top-up; `welcome` — automatic signup credit; `manual` — internal grant by the Dial team.
    - `invoiceId` string, nullable — Stripe invoice id backing this deposit (only `card` top-ups have one; null otherwise). Pass it to Download an invoice to get the Stripe-hosted invoice and PDF.
  - `pricing` BillingPricing — Per-number subscription unit prices (USD cents), read from Stripe (the source of truth). Stripe is a dependency of this endpoint.
    - `monthlyCents` integer — Per-number price billed monthly.
    - `annualCents` integer — Per-number price billed annually.
  - `paymentMethods` BillingPaymentMethodsItems[] — 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.
    - `id` string — Stripe PaymentMethod id (pm_…).
    - `type` string — Stripe PaymentMethod type: card, link, …
    - `brand` string — Card brand (visa, mastercard, amex, …); empty for non-card methods.
    - `last4` string — Card last four; empty for non-card methods.
    - `expMonth` integer — Card expiry month; 0 for non-card methods.
    - `expYear` integer — Card expiry year; 0 for non-card methods.
    - `email` string, nullable — Identifying email for account-style methods (e.g. Link); null otherwise.
    - `isDefault` boolean — True for the customer's default payment method (invoices + subscription renewals).

## Other responses

- `401` — Missing or invalid API key.

---

[API](https://skmtc.net/getdial/apis/rest-api.md) · [All operations](https://skmtc.net/getdial/apis/rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/getdial/rest-api/revisions/5f4eb30ac29a/schema)