# Follow usage (/docs/usage-billing/follow-usage)

Ways to see usage before and after it is billed. All times are in UTC.

## This period so far [#this-period-so-far]

For each agreement, Comecero works out the usage not billed yet the same way the next invoice will: what was used, what the plan includes, and what the usage above the allowance comes to so far (before prepaid credit).

- **In the dashboard**: **Usage Billing**, the **Customers** tab, open the customer. The **This period so far** card shows it per metric, with the **Estimated usage charge**.
- **With the API**: [Get usage this period so far](/api/usage-agreements/get-usage-so-far) (`GET /api/v1/usage/agreements/{agreement_id}/current`). Each entry in `entitlements` has `used`, `included`, `percent` (rounded down, `null` when nothing is included) and `amount` (before prepaid credit). `period_end` is `null` when the subscription has no next renewal.

It is cached for 5 minutes, so it can be a few minutes behind.

## The shopper's own usage [#the-shoppers-own-usage]

Customers see their own usage on their account in your shop: under **Subscriptions**, the **Usage this period** card shows each metric with what they used, what their plan includes, and a bar with the percent used. It shows no prices or amounts: the invoice says what is owed. It only appears for plans billed by use.

Your own app or customer portal can read the same with:

````bash
curl https://api.comecero.com/api/v1/customers/me/usage \
  -H "Authorization: Bearer $SHOPPER_TOKEN"
````

````json
{
  "object": "list",
  "data": [
    {
      "object": "customer_usage",
      "subscription_id": "SB0123456789",
      "plan_name": "Pro",
      "period_start": "2026-11-01T00:00:00Z",
      "period_end": "2026-12-01T00:00:00Z",
      "as_of": "2026-11-12T10:00:00Z",
      "metrics": [
        { "metric_name": "AI tokens", "unit_label": "token", "used": 830000, "included": 1000000, "percent": 83 }
      ]
    }
  ]
}
````

See [Get a customer's usage this period](/api/usage/get-customer-usage).

- `{customer_id}` is the **Comecero** customer id of the subscription's customer, or `me` with a shopper's token. It is not the `customer_id` of the agreement, which is your own id. A shopper's token reads only its own customer. A secret token can read any customer.
- One entry per active agreement on the customer's subscriptions, at most 20. `plan_name` is the name of what the customer bought.
- Cached for 5 minutes. With usage billing turned off, `data` is empty: a shopper never sees an error about it.

## The events behind a bill [#the-events-behind-a-bill]

To check a bill or answer a dispute, look up a customer's events one UTC day at a time, up to 24 months back:

- **In the dashboard**: **Usage Billing**, the **Customers** tab, open the customer, then **View events**. Pick a day and, if you like, a metric. You see each event's time, quantity, operation id and properties.
- **With the API**: [List a customer's events](/api/usage/list-usage-events) (`GET /api/v1/usage/events?customer_id=...&date=YYYY-MM-DD`). Here `customer_id` is your own id, as sent in `external_customer_id`.

Events show here a few minutes after they are counted. Totals and invoices are never delayed by this.

The meter counts events for any `external_customer_id`, with or without an agreement. Events for an id with no agreement are counted but never billed. Check a new customer's events here to catch a wrong id early.

For totals over any range of whole hours (up to 366 days), use [Read counted usage](/api/usage/get-usage-summary) (`GET /api/v1/usage/summary?customer_id=...&metric_key=...&from=...&to=...`). It answers the total and each hour's value.

## Usage alerts [#usage-alerts]

Subscribe to the webhook event [`usage:threshold_reached`](/api/webhooks/usage-threshold-reached) (in the dashboard: **Webhooks > Event Subscriptions**) to hear when a customer passes **50%, 80% or 100%** of what their plan includes in the period not billed yet. Use it to send "running low" emails or offer an upgrade.

- Each threshold is sent once per entitlement and billing period.
- Checked every hour. If a customer jumps past several thresholds at once, only the highest is sent.
- Only entitlements with an included allowance send alerts.
- No alerts are sent while usage billing is turned off for your account.

Create the subscription in the dashboard or with the API. Send `"active": true`: a new event subscription is off until it is turned on.

````bash
curl -X POST https://api.comecero.com/api/v1/event_subscriptions \
  -H "Authorization: Bearer $COMECERO_SECRET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "usage:threshold_reached",
    "method": "http",
    "format": "json",
    "destination": "https://example.com/webhooks/comecero",
    "active": true
  }'
````

Comecero then posts each event to your URL, with `type` set to `usage:threshold_reached`. See the [webhooks guide](/docs/guides/webhooks) for deliveries and signatures. The usage alert is in the event's `data`:

````json
{
  "object": "usage_alert",
  "agreement_id": "agr_8412",
  "entitlement_id": "ent_8412_tokens",
  "customer_id": "cust_8412",
  "metric_id": "met_ai_tokens",
  "metric_key": "ai_tokens",
  "threshold": 80,
  "percent": 83,
  "used": 830000,
  "included": 1000000,
  "period_start": "2026-11-01T00:00:00Z",
  "period_end": "2026-12-01T00:00:00Z"
}
````

- `customer_id` is your own id from the agreement, not the Comecero customer id.
- `threshold` is the threshold crossed: 50, 80 or 100.
- `percent` is rounded down, so 100 means everything included is used.
- `period_end` is `null` when the subscription has no next renewal.

A delivery looks like this (some event fields are left out here):

````json
{
  "object": "event",
  "event_id": "EV0123456789",
  "type": "usage:threshold_reached",
  "test": false,
  "account_id": "AB1234",
  "date_created": "2026-11-24T14:00:12Z",
  "data": {
    "object": "usage_alert",
    "agreement_id": "agr_8412",
    "entitlement_id": "ent_8412_tokens",
    "customer_id": "cust_8412",
    "metric_id": "met_ai_tokens",
    "metric_key": "ai_tokens",
    "threshold": 100,
    "percent": 104,
    "used": 1040000,
    "included": 1000000,
    "period_start": "2026-11-01T00:00:00Z",
    "period_end": "2026-12-01T00:00:00Z"
  }
}
````

Use `customer_id` (your own id) and `metric_key` to find the customer in your app. Ideas: email "you have used 80% of your tokens" at 80, offer an upgrade or a credit top-up at 100, or stop usage in your app at 100 when the entitlement's `overage_policy` is `block`.
