---
title: "Retrieve usage so far for each of a customer's metered subscriptions"
description: "One current_usage per subscription that has a metered item and an open usage window, newest first, at most 50 (has_more says more exist)."
canonical_url: "https://twominutebilling.com/help/developers/api-reference/customers/retrieve-usage-so-far-for-each-of-a-customer-s-m"
---
# Retrieve usage so far for each of a customer's metered subscriptions

> One current_usage per subscription that has a metered item and an open usage window, newest first, at most 50 (has_more says more exist).

<api-operation method="GET" path="/v1/businesses/{biz}/customers/{cus}/current_usage">
<template v-slot:docs="">

One `current_usage` per subscription that has a metered item and an open usage window, newest first, at most 50 (`has_more` says more exist). `totals` sums each currency on its own; currencies are never added together or converted.

## Path parameters

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        biz
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <strong>
        yes
      </strong>
    </td>
    
    <td>
      Business id (biz_…)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        cus
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <strong>
        yes
      </strong>
    </td>
    
    <td>
      Customer id (cus_…)
    </td>
  </tr>
</tbody>
</table>

## Query parameters

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        include_projection
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      <code>
        true
      </code>
      
       adds a projection to window end: the projected quantity is rated as the invoice rates it (a sum or count extends at the current rate, a level holds), plus any minimum-spend true-up. Null before 10% of the window has passed.
    </td>
  </tr>
</tbody>
</table>

## Response

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The object type; always <code>
        list
      </code>
      
      . One of <code>
        list
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        customer
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The customer id.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data
      </code>
    </td>
    
    <td>
      <code>
        array of object
      </code>
    </td>
    
    <td>
      One entry per subscription.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.object
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The object type; always <code>
        current_usage
      </code>
      
      . One of <code>
        current_usage
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.subscription
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The subscription id.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.currency
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The subscription's currency.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.as_of
      </code>
    </td>
    
    <td>
      <code>
        string · ISO-8601
      </code>
    </td>
    
    <td>
      The instant the usage was read.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.window
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      The usage window, or null when no invoice will bill usage.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.items
      </code>
    </td>
    
    <td>
      <code>
        array of object
      </code>
    </td>
    
    <td>
      The metered items.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.settled_charges
      </code>
    </td>
    
    <td>
      <code>
        array of object
      </code>
    </td>
    
    <td>
      Usage settled early (an item removed, a term reset).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.subtotal_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      Sum of the item amounts and settled charges.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.tax_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      Tax on the subtotal, inclusive tax included.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.tax_lines
      </code>
    </td>
    
    <td>
      <code>
        array of object
      </code>
    </td>
    
    <td>
      Exclusive tax by component.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.total_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      Subtotal plus exclusive tax.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.projection
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      Totals at window end, or null when not asked for or when less than 10% of the window has passed.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.discounts_applied
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      Always false: coupons and credits are not applied here.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.trial
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      Usage recorded during the trial, with no amount: no invoice bills it. Null outside a trial.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        has_more
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      True if the customer has more than 50 metered subscriptions.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        totals
      </code>
    </td>
    
    <td>
      <code>
        array of object
      </code>
    </td>
    
    <td>
      One row per currency. Currencies are never summed together.
    </td>
  </tr>
</tbody>
</table>

## Status codes

<table>
<thead>
  <tr>
    <th>
      Status
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        200
      </code>
    </td>
    
    <td>
      List of current_usage
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        400
      </code>
    </td>
    
    <td>
      Unknown query parameter
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        404
      </code>
    </td>
    
    <td>
      No such customer
    </td>
  </tr>
</tbody>
</table>
</template>

<template v-slot:request="">

```bash [Request]
curl "$TMBILLING_URL/v1/businesses/biz_XXXXXXXXXXXX01/customers/cus_XXXXXXXXXXXX01/current_usage" \
  -H "Authorization: Bearer $TMBILLING_API_KEY"
```

</template>

<template v-slot:response="">
<code-group>

```json [200 OK]
{
  "object": "list",
  "customer": "cus_XXXXXXXXXXXX01",
  "data": [
    {
      "object": "current_usage",
      "currency": "INR",
      "as_of": "2026-03-14T09:30:00Z",
      "window": {
        "start": "2026-03-14T09:30:00Z",
        "end": "2026-04-14T09:30:00Z",
        "billed_by": "renewal"
      },
      "items": [
        {
          "item": "si_XXXXXXXXXXXX01",
          "price": "api-calls-inr",
          "name": "API calls",
          "model": "usage",
          "aggregation": "sum",
          "quantity": 4000
        }
      ],
      "subtotal_minor": 150000,
      "tax_minor": 27000,
      "total_minor": 177000
    }
  ],
  "has_more": false,
  "totals": [
    {
      "currency": "INR",
      "subtotal_minor": 150000,
      "tax_minor": 27000,
      "total_minor": 177000,
      "projected_total_minor": 672600
    }
  ]
}
```

```json [400 Bad Request]
{
  "error": {
    "type": "invalid_request_error",
    "message": "Unknown query parameter"
  }
}
```

```json [404 Not Found]
{
  "error": {
    "type": "invalid_request_error",
    "message": "No such customer"
  }
}
```

</code-group>
</template>
</api-operation>


## Sitemap

See the full [sitemap](https://twominutebilling.com/sitemap.md) for all pages.