---
title: "Retrieve usage so far in the current billing window"
description: "Read-only; nothing is stored."
canonical_url: "https://twominutebilling.com/help/developers/api-reference/subscriptions/retrieve-usage-so-far-in-the-current-billing-win"
---
# Retrieve usage so far in the current billing window

> Read-only; nothing is stored.

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

Rates the usage recorded in the window the next invoice bills, as that invoice will rate it (free units, tiers, packages, percentages), and adds tax with the customer's tax settings. Discounts and credits are not applied (`discounts_applied: false`); for the exact next invoice, call `renewal_estimate?include_usage_so_far=true`. Usage already settled early (an item removed, a term reset) is listed in `settled_charges` and counted in the totals, since the next invoice bills it. `window` is null when no invoice will bill usage (a trial, a cancelled subscription, or a window already billed); during a trial, `trial` lists the units recorded, with no amount.

## 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>
        sub
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <strong>
        yes
      </strong>
    </td>
    
    <td>
      Subscription id (sub_…)
    </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>
        current_usage
      </code>
      
      . One of <code>
        current_usage
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        subscription
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The subscription id.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        currency
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The subscription's currency.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        as_of
      </code>
    </td>
    
    <td>
      <code>
        string · ISO-8601
      </code>
    </td>
    
    <td>
      The instant the usage was read.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        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>
        items
      </code>
    </td>
    
    <td>
      <code>
        array of object
      </code>
    </td>
    
    <td>
      The metered items.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        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>
        subtotal_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      Sum of the item amounts and settled charges.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tax_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      Tax on the subtotal, inclusive tax included.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tax_lines
      </code>
    </td>
    
    <td>
      <code>
        array of object
      </code>
    </td>
    
    <td>
      Exclusive tax by component.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        total_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      Subtotal plus exclusive tax.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        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>
        discounts_applied
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      Always false: coupons and credits are not applied here.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        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>
</tbody>
</table>

## Status codes

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

<tbody>
  <tr>
    <td>
      <code>
        200
      </code>
    </td>
    
    <td>
      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 subscription
    </td>
  </tr>
</tbody>
</table>
</template>

<template v-slot:request="">

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

</template>

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

```json [200 OK]
{
  "object": "current_usage",
  "subscription": "sub_XXXXXXXXXXXX01",
  "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",
    "invoice": "inv_XXXXXXXXXXXX01"
  },
  "items": [
    {
      "item": "si_XXXXXXXXXXXX01",
      "price": "api-calls-inr",
      "name": "API calls",
      "model": "usage",
      "aggregation": "sum",
      "quantity": 4000
    }
  ],
  "settled_charges": [
    {
      "id": "uch_XXXXXXXXXXXX01",
      "price": "api-calls-inr",
      "name": "API calls",
      "description": "usage (api-calls-inr) 120 units",
      "quantity": 120,
      "amount_minor": 6000
    }
  ],
  "subtotal_minor": 150000,
  "tax_minor": 27000,
  "tax_lines": [
    {
      "label": "CGST 9%",
      "amount_minor": 13500
    }
  ],
  "total_minor": 177000,
  "projection": {
    "subtotal_minor": 570000,
    "minimum_true_up_minor": 0,
    "tax_minor": 102600,
    "tax_lines": [
      {
        "label": "CGST 9%",
        "amount_minor": 51300
      }
    ],
    "total_minor": 672600
  },
  "discounts_applied": false,
  "trial": {
    "start": "2026-03-14T09:30:00Z",
    "end": "2026-04-14T09:30:00Z",
    "items": [
      {
        "item": "si_XXXXXXXXXXXX01",
        "price": "api-calls-inr",
        "name": "API calls",
        "quantity": 250
      }
    ]
  }
}
```

```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 subscription"
  }
}
```

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


## Sitemap

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