> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracklysms.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Billing Records

> Individual charge and refund records, with cursor pagination and an updatedSince reconciliation watermark.

Returns individual billing records (charges, adjustments, refunds) for the caller and its children. Supports the same [reconciliation](/api-reference/v2/messages/reconciliation) pattern as messages — pass `updatedSince` to pull only what changed.

## Query Parameters

<ParamField query="childAccountId" type="integer">
  Restrict to one owned child.
</ParamField>

<ParamField query="chargeType" type="string">
  Filter by charge type (e.g. `usage`).
</ParamField>

<ParamField query="status" type="string">
  Filter by record status (e.g. `succeeded`, `refunded`).
</ParamField>

<ParamField query="updatedSince" type="string">
  Reconciliation watermark (ISO-8601). Returns records changed after this time, newest-first within the cursor.
</ParamField>

<ParamField query="cursor" type="string">
  Opaque pagination cursor from a previous response's `next_cursor`.
</ParamField>

<ParamField query="limit" type="integer" default="50">
  Page size, max 200.
</ParamField>

## Response Fields

<ResponseField name="records" type="array">
  Array of billing records.

  <Expandable title="billing record">
    <ResponseField name="id" type="string">Record ID.</ResponseField>
    <ResponseField name="account_id" type="integer">Owning account.</ResponseField>
    <ResponseField name="external_ids" type="object">External IDs (e.g. `location_id`).</ResponseField>
    <ResponseField name="charge_type" type="string">Type of charge (e.g. `usage`).</ResponseField>
    <ResponseField name="trigger_reason" type="string">What produced the record (e.g. `monthly_billing`, `carrier_trueup`).</ResponseField>
    <ResponseField name="status" type="string">e.g. `succeeded`, `refunded`.</ResponseField>
    <ResponseField name="amount" type="number">Charge amount.</ResponseField>
    <ResponseField name="currency" type="string">Currency.</ResponseField>
    <ResponseField name="messages_count" type="integer">Messages covered.</ResponseField>
    <ResponseField name="segments_count" type="integer">Segments covered.</ResponseField>
    <ResponseField name="refund_amount_total" type="number">Total refunded against this record.</ResponseField>
    <ResponseField name="refunded_at" type="string">When refunded, if applicable.</ResponseField>
    <ResponseField name="is_adjustment" type="boolean">`true` for true-up / write-off adjustments.</ResponseField>
    <ResponseField name="period_start" type="string">Billing period start.</ResponseField>
    <ResponseField name="period_end" type="string">Billing period end.</ResponseField>
    <ResponseField name="created_at" type="string">Creation time.</ResponseField>
    <ResponseField name="updated_at" type="string">Last-change time; the reconciliation watermark field.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">`limit`, `has_more`, `next_cursor`.</ResponseField>

## Examples

<RequestExample>
  ```bash cURL theme={null}
  curl -G https://api.tracklysms.com/api/v2/billing/records \
    -H "X-Api-Key: trk_your_parent_key" \
    --data-urlencode "updatedSince=2026-07-01T00:00:00Z" \
    --data-urlencode "limit=200"
  ```
</RequestExample>

<ResponseExample>
  ```json Success (200) theme={null}
  {
    "records": [
      {
        "id": "66a0f7c84a1d4b2e9c3a1f2e",
        "account_id": 1042,
        "external_ids": { "location_id": "loc_west" },
        "charge_type": "usage",
        "trigger_reason": "monthly_billing",
        "status": "succeeded",
        "amount": 42.11,
        "currency": "usd",
        "messages_count": 9000,
        "segments_count": 9300,
        "refund_amount_total": 0.0,
        "refunded_at": null,
        "is_adjustment": false,
        "period_start": "2026-06-01T00:00:00Z",
        "period_end": "2026-07-01T00:00:00Z",
        "created_at": "2026-07-01T00:12:00Z",
        "updated_at": "2026-07-01T00:12:00Z"
      }
    ],
    "pagination": { "limit": 200, "has_more": false, "next_cursor": null }
  }
  ```
</ResponseExample>

## Error Codes

| HTTP Status | Error Code              | Description                                 |
| ----------- | ----------------------- | ------------------------------------------- |
| 400         | `invalid_updated_since` | `updatedSince` is not valid ISO-8601.       |
| 400         | `invalid_cursor`        | The pagination cursor is malformed.         |
| 400         | `invalid_child`         | `childAccountId` is malformed.              |
| 404         | `child_not_found`       | The `childAccountId` is not an owned child. |