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

# Metered billing

# Metered Billing & Usage Reporting

Fype supports usage-based pricing models, allowing you to charge customers based on their actual consumption during a billing cycle.

***

## Usage Reporting Flow

To implement metered billing, your application reports usage events to Fype as they occur. Fype tracks and aggregates these events to calculate the total amount due when the billing cycle closes.

***

## Reporting Consumption Events

Whenever a customer consumes a metered feature (e.g., processes LLM tokens, transfers files, or makes API requests), report the usage event to Fype.

* **Endpoint**: `POST /v1/usage/events`
* **Request Parameters**:
  * `subscription_id`: The subscription UUID to attribute usage to.
  * `event_type`: The metric name (e.g., `api_tokens`, `file_storage`).
  * `quantity`: Float value representing the consumed units.
  * `unit`: Description of units (e.g. `tokens`, `gigabytes`).
  * `metadata`: Optional key-value object containing details (e.g. `{"model": "gpt-4o"}`).

### API Request

```bash theme={null}
curl -X POST https://api.fype.dev/v1/usage/events \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subscription_id": "8ec755a5-9bb5-48b2-b430-6dfd86419515",
    "event_type": "api_tokens",
    "quantity": 1500.5,
    "unit": "tokens",
    "metadata": {
      "model": "gpt-4o"
    }
  }'
```

### Python SDK Request

```python theme={null}
from fype import Fype

fype = Fype(api_key="fype_test_...")

fype.usage.report(
    subscription_id="8ec755a5-9bb5-48b2-b430-6dfd86419515",
    event_type="api_tokens",
    quantity=1500.5,
    unit="tokens",
    metadata={"model": "gpt-4o"}
)
```

***

## Retrieving Usage Summaries

To audit consumption or show real-time limits in your client application, retrieve the aggregated usage summary for a subscription:

* **Endpoint**: `GET /v1/usage/summary?subscription_id={subscription_uuid}`

### Example Response

```json theme={null}
{
  "subscription_id": "8ec755a5-9bb5-48b2-b430-6dfd86419515",
  "aggregations": [
    {
      "id": "agg_uuid",
      "billing_period_start": "2026-06-01T00:00:00Z",
      "billing_period_end": "2026-07-01T00:00:00Z",
      "event_type": "api_tokens",
      "total_quantity": 482930.5,
      "unit": "tokens"
    }
  ]
}
```