# Usages

> For the complete machine-readable documentation index, see [llms.txt](https://apidocs.chargebee.com/llms.txt).


**Advanced Usage-Based Billing**

For high-scale usage ingestion, use [Advanced Usage-Based Billing](https://www.chargebee.com/docs/billing/2.0/usage-based-billing/understanding-usages) with the [Usage Events API](/docs/api/usage_events). The Usage Events API supports schemaless event ingestion at scale, including [individual events](/docs/api/usage_events/create-a-usage-event), [batch ingestion](/docs/api/usage_events/ingest-usages-in-batch), and [usage file ingestion](/docs/api/usage_files/usage-file-object).

The Usages API is used to record usage for metered item prices in a subscription. This API is only applicable when Automated Metered Billing is enabled in Chargebee.

Metered items are those that are billed based on the service usage. Common examples include:

-   Internet data services.
-   SMS send/receive services.
-   API services that are billed for the number of API calls made, say, per month.

An [item](/docs/api/items) is marked metered by setting its `metered` attribute as `true`. Only recurring items can be can be set as `metered`. Recurring items are those of `type` `plan` or `addon`. A subscription can have both metered and non-metered items. The usages API (described in this page), is used to add, retrieve and delete usages for the metered items in a subscription.

#### Invoicing Metered Item Prices[](#invoicing-metered-item-prices)

While non-metered items are invoiced in a prepaid manner at the beginning of each billing cycle; for metered items, the charges are raised at the end of the billing term (postpaid). During the course of the billing period, [usages can be added](/docs/api/usages/create-a-usage) as and when they occur. For a given `subscription_id` and `item_price_id`, there can be only one usage record for a specific `usage_date`. At the end of each term, the invoice is generated with `status` as `pending`. Any remaining usage records can continue to be added to the subscription until the invoice [closes automatically](https://www.chargebee.com/docs/billing/2.0/usage-based-billing/metered_billing#configuring-metered-billing) or is [closed via an API call](/docs/api/invoices/close-a-pending-invoice). If a usage record has erroneous information and you want to correct it, [delete the usage](/docs/api/usages/delete-a-usage) and add it again.

**Max Usages**

-   Legacy metered billing applies per-subscription usage limits over the subscription lifetime. [Contact Support](https://www.chargebee.com/docs/billing/2.0/kb/getting-started/how-to-contact-chargebees-support-team?utm_source=docs_api&utm_medium=content&utm_campaign=support) for the limit applicable to your site or to request an increase. For high-volume usage at scale, see [Usage-Based Billing](https://www.chargebee.com/docs/billing/2.0/usage-based-billing/understanding-usages).
-   If there are no usages for an item price, the item price is not invoiced.

## Sample Usage

```json
{
  "usage": {
    "created_at": 1601708190,
    "id": "usage_XpbBrciSCKqKwGe",
    "item_price_id": "silver-usd",
    "note": "Day 1 usage from __test__XpbBrciSCKqKp4Z",
    "object": "usage",
    "quantity": "5",
    "resource_version": 1601708190709,
    "subscription_id": "__test__XpbBrciSCKqKsNb",
    "updated_at": 1601708190,
    "usage_date": 1601718990
  }
}
```

## Usages attributes

## Input Parameters

- `id` (optional, string, max chars=100)
  A unique and immutable id for the usage. If not provided, it is autogenerated.

- `usage_date` (required, timestamp(UTC) in seconds)
  The time at which this usage occurred. Chargebee bills only those usages whose `usage_date` falls within a time when the subscription `status` was `active` or `non_renewing`. However, the remaining usage records are still stored and are [retrievable](/docs/api/usages/retrieve-a-usage).
  
  **Note:** If `usage_date` corresponds to a time already invoiced, then it is stored but never invoiced unless the [invoice is regenerated](/docs/api/subscriptions/regenerate-an-invoice) .

- `subscription_id` (required, string, max chars=100)
  The id of the [subscription](/docs/api/subscriptions) to which this usage record belongs.

- `item_price_id` (required, string, max chars=100)
  The id of the [item price](/docs/api/item_prices) to which this usage belongs. The item price must be a part of the subscription or should have been part of it historically.

- `invoice_id` (optional, string, max chars=100)
  When the usage has been invoiced, this is the `id` of the [invoice](/docs/api/invoices). This is cleared when the invoice is `voided` or deleted.

- `line_item_id` (optional, string, max chars=100)
  When the usage has been invoiced, this is the `id` of the `[invoice.line_item](/docs/api/invoices/invoice-object#line_items)` that the usage is for. This is cleared when the invoice is `[voided](/docs/api/invoices/void-an-invoice)` or [deleted](/docs/api/invoices/delete-an-invoice) .

- `quantity` (required, string, max chars=40)
  The quantity specified for this usage record.

- `source` (optional, enumerated string)
  The source from which the usage record was created.
  Possible enum values:
    - `admin_console`
      Operation made through the Chargebee admin UI
    - `api`
      Operation made through the API
    - `bulk_operation`
      Operation that are triggerd through bulk operation.

- `note` (optional, string, max chars=500)
  A note for this usage record. This note is not displayed on any customer-facing document or interface such as [invoice PDFs](/docs/api/invoices/retrieve-invoice-as-pdf) or [Hosted Pages](/docs/api/hosted_pages) .

- `resource_version` (optional, long)
  Version number of this resource. The `resource_version` is updated with a new timestamp in milliseconds for every change made to the resource. This attribute will be present only if the resource has been updated after 2016-09-28.

- `updated_at` (optional, timestamp(UTC) in seconds)
  Timestamp indicating when this usage resource was last updated.

- `created_at` (required, timestamp(UTC) in seconds)
  Timestamp indicating when the item was created.