Sign in

v51

latestOpenAPI 3.0.0raw.githubusercontent.com2026-08-014102371.0 MB
Billing

Get a billing record by ID

Retrieves a single billing record by its unique identifier. Returns only the billing record without related account or reference resource data.

get/billings/{billing-id}

Path parameters

billing-idstring uuid required

The unique identifier of the billing record

Response

Successfully retrieved billing record

idstring uuid

The unique identifier of the billing.

customer_idstring uuid

The customer's unique identifier. Returned from the GET /customers response.

account_idstring uuid

The billing account ID. Returned from the GET /billing_accounts/{id} response.

transaction_type'usage' | 'top_up' | 'adjustment' | 'refund'

The nature of the ledger entry.

status'progressing' | 'end' | 'pending' | 'finished'

Status of the billing.

reference_type'' | 'call' | 'call_extension' | 'sms' | 'email' | 'number' | 'number_renew' | 'credit_free_tier' | 'monthly_allowance' | 'credit_adjustment' | 'token_adjustment' | 'speaking' | 'recording'

The type of reference associated with this billing.

reference_idstring uuid

The unique identifier of the referenced resource. The actual resource type is determined by reference_type. Returned from the corresponding resource endpoint.

cost_type'' | 'call_pstn_outgoing' | 'call_pstn_incoming' | 'call_vn' | 'call_extension' | 'call_direct_ext' | 'sms' | 'email' | 'number' | 'number_renew' | 'tts' | 'recording'

The classification of the billing cost.

usage_durationinteger

The actual usage duration in seconds.

billable_unitsinteger

The number of billable units (e.g. minutes, rounded up).

rate_token_per_unitinteger

The token rate per billable unit.

rate_credit_per_unitinteger

The credit rate per billable unit in micros.

amount_tokeninteger

The token delta for this transaction (negative for usage, positive for top-up).

amount_creditinteger

The credit delta for this transaction in micros (negative for usage, positive for top-up).

balance_token_snapshotinteger

The token balance after this transaction.

balance_credit_snapshotinteger

The credit balance after this transaction in micros.

idempotency_keystring uuid

A unique key to prevent duplicate transactions.

tm_billing_startstring date-time

The start timestamp of the billing period.

tm_billing_endstring date-time

The end timestamp of the billing period.

tm_createstring date-time

The creation timestamp.

tm_updatestring date-time

The last update timestamp.

tm_deletestring date-time

The deletion timestamp, if applicable.

Example response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "customer_id": "7c4d2f3a-1b8e-4f5c-9a6d-3e2f1a0b4c5d",
  "account_id": "b8c9d0e1-f2a3-4567-8901-23456789abcd",
  "transaction_type": "usage",
  "status": "progressing",
  "reference_type": "call",
  "reference_id": "f6a7b8c9-d0e1-2345-6789-0abcdef01234",
  "cost_type": "call_pstn_outgoing",
  "usage_duration": 125,
  "billable_units": 3,
  "rate_token_per_unit": 10,
  "rate_credit_per_unit": 50000,
  "amount_token": -30,
  "amount_credit": -150000,
  "balance_token_snapshot": 470,
  "balance_credit_snapshot": 1350000,
  "idempotency_key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "tm_billing_start": "2026-01-15T09:30:00.000000Z",
  "tm_billing_end": "2026-01-15T09:30:00.000000Z",
  "tm_create": "2026-01-15T09:30:00.000000Z",
  "tm_update": "2026-01-15T09:30:00.000000Z",
  "tm_delete": "2026-01-15T09:30:00.000000Z"
}