> ## 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

> Access monthly billing statements and their associated transactions.

<Tabs>
  <Tab title="v3">
    <Note>Recommended for all new integrations.</Note>

    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 />

    ## 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 />

    ## 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 />

    ## 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`                                |
  </Tab>

  <Tab title="v2">
    ## What is the Billing Statements API?

    The **Billing Statements API (v2)** provides access to your company's monthly billing statements. Each statement summarizes expenses and payments made during a given billing cycle.

    You can use this API to:

    * Retrieve the **current billing statement** (the active billing cycle)
    * Retrieve a **past billing statement** by specifying the month and year
    * Automate reconciliation and reporting processes

    <br />

    ## Available Endpoints

    | Operation                     | Endpoint                                | Method |
    | ----------------------------- | --------------------------------------- | ------ |
    | Get current billing statement | `/v2/billing-statements/current`        | GET    |
    | Get billing statement by date | `/v2/billing-statements/{month}/{year}` | GET    |

    <br />

    ## Get current billing statement

    Retrieve the billing statement that is currently open for the ongoing cycle.

    ### Endpoint

    `GET /v2/billing-statements/current`

    ### cURL Request

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

    ### Sample JSON Response

    ```json JSON theme={null}
    {
      "month": 7,
      "year": 2025,
      "status": "OPEN",
      "statementUuid": "b6a81f58-4ebc-4e93-822d-2b0917ae845c",
      "totalAmount": 150000.50,
      "currency": "MXN",
      "closingDate": "2025-07-31"
    }

    ```

    <br />

    ## Get current billing statement

    Retrieve a billing statement for a specific month and year (e.g. June 2024).

    ### Endpoint

    `GET /v2/billing-statements/{month}/{year}`

    ### cURL Request

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

    ### Sample JSON Response

    ```json JSON theme={null}
    {
      "month": 6,
      "year": 2024,
      "status": "CLOSED",
      "statementUuid": "e1f349d4-cf35-4b78-bdbf-1d35f0a8e014",
      "totalAmount": 132500.00,
      "currency": "MXN",
      "closingDate": "2024-06-30"
    }

    ```

    <br />

    \*\*💡 Tip: \*\*Use the status field to distinguish between open and closed billing cycles.

    **⚠️ Note:** The current billing statement is subject to change until the cycle closes.

    ***

    ## Endpoint Reference

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

    List billing statements (v2)

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

    | Field           | Type                              | Example |
    | --------------- | --------------------------------- | ------- |
    | `content`       | array of BillingStatementResponse |         |
    | `totalElements` | integer                           |         |
    | `totalPages`    | integer                           |         |
    | `size`          | integer                           |         |
    | `number`        | integer                           |         |
  </Tab>
</Tabs>