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

# Billing Statements API

> Access monthly billing statements and their associated transactions.

The API provides endpoints to:

1. **Retrieve all billing statements**
2. **Retrieve a specific billing statement by UUID**
3. **Retrieve all transactions from a specific billing statement**

Each of these endpoints returns structured financial data, including statement periods, totals, and associated transaction details.

<br />

## 1⃣ Retrieve All Billing Statements

Use this endpoint to list **all billing statements** associated with the account.

### Endpoint

`GET /v3/billing-statements`

### cURL Request

```curl cURL theme={null}
curl -X GET \
"https://public-api.mx.clara.com/api/v3/billing-statements" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

### Sample JSON Response

```curl JSON theme={null}
[
  {
    "uuid": "e4a50134-447f-4c34-b6b6-78cdb43d3fd5",
    "statementStartDate": "2024-06-01",
    "statementEndDate": "2024-06-30",
    "currency": "MXN",
    "totalAmount": 10000.00
  }
]
```

<br />

## 2⃣ Retrieve a Billing Statement by UUID

Use this endpoint to retrieve the full details of a specific billing statement, including amounts, dates, and metadata.

### Endpoint

`GET /v3/billing-statements/{uuid}`

### cURL Request

```curl cURL theme={null}
curl -X GET \
"https://public-api.mx.clara.com/api/v3/billing-statements/e4a50134-447f-4c34-b6b6-78cdb43d3fd5" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

### Sample JSON Response

```curl JSON theme={null}
{
  "uuid": "e4a50134-447f-4c34-b6b6-78cdb43d3fd5",
  "currency": "MXN",
  "totalAmount": 10000.00,
  "statementStartDate": "2024-06-01",
  "statementEndDate": "2024-06-30",
  "status": "closed",
  "generatedAt": "2024-07-01T10:00:00Z"
}
```

<br />

## 3⃣ Retrieve Transactions from a Billing Statement

Use this endpoint to get all transactions associated with a given billing statement.

### Endpoint

`GET /v3/billing-statements/{uuid}/transactions`

### cURL Request

```curl cURL theme={null}
curl -X GET \
"https://public-api.mx.clara.com/api/v3/billing-statements/e4a50134-447f-4c34-b6b6-78cdb43d3fd5/transactions" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

### Sample JSON Response

```curl JSON theme={null}
[
  {
    "uuid": "0fa38f1b-8ae6-4ac6-9171-d3dba4dfecbe",
    "amount": 1200.00,
    "currency": "MXN",
    "description": "Flight booking",
    "category": "Travel",
    "date": "2024-06-10"
  }
]
```

💡 Tip: Billing statements and their transactions are useful for automating your month-end reconciliation process.

⚠️ Note: The sample data shown is for illustrative purposes only and does not represent actual financial or tax calculations.

***

## Endpoint Reference

### `GET /api/v3/billing-statements`

List billing statements (v3)

**Response Schema (`BillingStatementPageV3`):**

| Field           | Type                              | Example |
| --------------- | --------------------------------- | ------- |
| `content`       | array of BillingStatementResponse |         |
| `totalElements` | integer                           |         |
| `totalPages`    | integer                           |         |
| `size`          | integer                           |         |
| `number`        | integer                           |         |

### `GET /api/v3/billing-statements/current`

Get current billing statement (v3)

**Response Schema (`BillingStatementResponse`):**

| Field              | Type          | Example                                |
| ------------------ | ------------- | -------------------------------------- |
| `uuid`             | string (uuid) | `221e5a80-0123-1d02-1e23-1fe23d74f5e6` |
| `periodStartDate`  | string (date) | `2025-08-03`                           |
| `periodEndDate`    | string (date) | `2025-09-02`                           |
| `statementDate`    | string (date) | `2025-09-02`                           |
| `currentBalance`   | string        | `750.01`                               |
| `requiredPayment`  | string        | `750.01`                               |
| `paymentLimitDate` | string (date) | `2025-09-12`                           |
| `paidAmount`       | string        | `800.01`                               |
| `unpaid`           | boolean       | `False`                                |

### `GET /api/v3/billing-statements/{uuid}`

Get billing statement by UUID (v3)

**Parameters:**

| Parameter | In   | Type          | Required | Description |
| --------- | ---- | ------------- | -------- | ----------- |
| `uuid`    | path | string (uuid) | ✅        |             |

**Response Schema (`BillingStatementResponse`):**

| Field              | Type          | Example                                |
| ------------------ | ------------- | -------------------------------------- |
| `uuid`             | string (uuid) | `221e5a80-0123-1d02-1e23-1fe23d74f5e6` |
| `periodStartDate`  | string (date) | `2025-08-03`                           |
| `periodEndDate`    | string (date) | `2025-09-02`                           |
| `statementDate`    | string (date) | `2025-09-02`                           |
| `currentBalance`   | string        | `750.01`                               |
| `requiredPayment`  | string        | `750.01`                               |
| `paymentLimitDate` | string (date) | `2025-09-12`                           |
| `paidAmount`       | string        | `800.01`                               |
| `unpaid`           | boolean       | `False`                                |