> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.getdial.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.getdial.ai/_mcp/server. # Get billing status GET https://getdial.ai/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. Reference: https://docs.getdial.ai/api-reference/rest-api/billing/get-billing ## OpenAPI Specification ```yaml openapi: 3.1.0 info: title: rest version: 1.0.0 paths: /api/v1/billing: get: operationId: get-billing summary: Get billing status description: >- Returns the account's credit-wallet balance, the current subscription (if any), each phone number's billing mode (PAYG or FIXED), and recent usage. tags: - subpackage_billing parameters: - name: Authorization in: header description: 'Your Dial API key, sent as `Authorization: Bearer sk_live_...`' required: true schema: type: string responses: '200': description: Billing status. content: application/json: schema: $ref: '#/components/schemas/Billing' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' servers: - url: https://getdial.ai description: Dial API (provisional host) components: schemas: BillingSubscriptionInterval: type: string enum: - monthly - annual title: BillingSubscriptionInterval BillingSubscription: type: object properties: periodStart: type: string format: date-time periodEnd: type: string format: date-time quantity: type: integer description: Number of subscribed phone numbers (one unit each). interval: $ref: '#/components/schemas/BillingSubscriptionInterval' cancelAtPeriodEnd: type: boolean description: >- 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. description: The current subscription, or null when the account is pay-as-you-go. title: BillingSubscription BillingNumbersItemsMode: type: string enum: - PAYG - FIXED description: PAYG bills the wallet; FIXED is covered by a subscription. title: BillingNumbersItemsMode BillingNumbersItems: type: object properties: id: type: string number: type: string nickname: type: - string - 'null' description: User-assigned label for the number, or null if unset. mode: $ref: '#/components/schemas/BillingNumbersItemsMode' description: PAYG bills the wallet; FIXED is covered by a subscription. title: BillingNumbersItems BillingDepositsItemsKind: type: string enum: - card - welcome - manual description: >- `card` — paid Stripe top-up; `welcome` — automatic signup credit; `manual` — internal grant by the Dial team. title: BillingDepositsItemsKind BillingDepositsItems: type: object properties: createdAt: type: string format: date-time amountCents: type: integer description: Amount credited, in USD cents (positive). kind: $ref: '#/components/schemas/BillingDepositsItemsKind' description: >- `card` — paid Stripe top-up; `welcome` — automatic signup credit; `manual` — internal grant by the Dial team. invoiceId: type: - string - 'null' description: >- 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. title: BillingDepositsItems BillingPricing: type: object properties: monthlyCents: type: integer description: Per-number price billed monthly. annualCents: type: integer description: Per-number price billed annually. description: >- Per-number subscription unit prices (USD cents), read from Stripe (the source of truth). Stripe is a dependency of this endpoint. title: BillingPricing BillingPaymentMethodsItems: type: object properties: id: type: string description: Stripe PaymentMethod id (pm_…). type: type: string description: 'Stripe PaymentMethod type: card, link, …' brand: type: string description: Card brand (visa, mastercard, amex, …); empty for non-card methods. last4: type: string description: Card last four; empty for non-card methods. expMonth: type: integer description: Card expiry month; 0 for non-card methods. expYear: type: integer description: Card expiry year; 0 for non-card methods. email: type: - string - 'null' description: >- Identifying email for account-style methods (e.g. Link); null otherwise. isDefault: type: boolean description: >- True for the customer's default payment method (invoices + subscription renewals). title: BillingPaymentMethodsItems Billing: type: object properties: balanceCents: type: integer description: Credit-wallet balance in USD cents. May be negative. subscription: oneOf: - $ref: '#/components/schemas/BillingSubscription' - type: 'null' description: The current subscription, or null when the account is pay-as-you-go. numbers: type: array items: $ref: '#/components/schemas/BillingNumbersItems' deposits: type: array items: $ref: '#/components/schemas/BillingDepositsItems' description: Recent credits added to the wallet, most recent first. pricing: $ref: '#/components/schemas/BillingPricing' description: >- Per-number subscription unit prices (USD cents), read from Stripe (the source of truth). Stripe is a dependency of this endpoint. paymentMethods: type: array items: $ref: '#/components/schemas/BillingPaymentMethodsItems' description: >- 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. description: Account billing status (GET /api/v1/billing). title: Billing ErrorError: oneOf: - type: string - type: object additionalProperties: description: Any type description: An error message, or a validation-error object for 400 responses. title: ErrorError Error: type: object properties: error: $ref: '#/components/schemas/ErrorError' description: An error message, or a validation-error object for 400 responses. title: Error securitySchemes: bearerAuth: type: http scheme: bearer description: 'Your Dial API key, sent as `Authorization: Bearer sk_live_...`' ``` ## Examples **Request** ```json {} ``` **Response** ```json { "balanceCents": 23500, "subscription": { "periodStart": "2024-04-01T00:00:00Z", "periodEnd": "2024-05-01T00:00:00Z", "quantity": 3, "interval": "monthly", "cancelAtPeriodEnd": false }, "numbers": [ { "id": "num_01F8ZJ2X9Y7K8QW3R4T5V6B7N8", "number": "+14155550123", "nickname": "Support line", "mode": "FIXED" }, { "id": "num_02G9YK3Z0A8L9RX4S5U6W7X8Y9", "number": "+14155550987", "nickname": "Sales", "mode": "PAYG" } ], "deposits": [ { "createdAt": "2024-04-10T15:45:00Z", "amountCents": 5000, "kind": "card", "invoiceId": "in_1QabcdEFghij" }, { "createdAt": "2024-03-01T12:00:00Z", "amountCents": 1000, "kind": "welcome", "invoiceId": null } ], "pricing": { "monthlyCents": 1200, "annualCents": 12000 }, "paymentMethods": [ { "id": "pm_1F8ZJ2X9Y7K8QW3R", "type": "card", "brand": "visa", "last4": "4242", "expMonth": 4, "expYear": 2027, "email": null, "isDefault": true }, { "id": "pm_2G9YK3Z0A8L9RX4S", "type": "link", "brand": "", "last4": "", "expMonth": 0, "expYear": 0, "email": "user@example.com", "isDefault": false } ] } ``` **SDK Code** ```python import requests url = "https://getdial.ai/api/v1/billing" payload = {} headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.get(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://getdial.ai/api/v1/billing'; const options = { method: 'GET', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://getdial.ai/api/v1/billing" payload := strings.NewReader("{}") req, _ := http.NewRequest("GET", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://getdial.ai/api/v1/billing") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://getdial.ai/api/v1/billing") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{}") .asString(); ``` ```php request('GET', 'https://getdial.ai/api/v1/billing', [ 'body' => '{}', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://getdial.ai/api/v1/billing"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://getdial.ai/api/v1/billing")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```