Settings
Configure SDK
Usages
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 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
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 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 or is closed via an API call. If a usage record has erroneous information and you want to correct it, delete the usage and add it again.
Max Usages
- The maximum number of usages that can be recorded for the entire lifetime of a subscription is 5000. Contact Support if you want this limit to be increased for your site.
- If there are no usages for an item price, the item price is not invoiced.
Sample usage [ JSON ]
{
"created_at": 1601708189,
"id": "usage_XpbBrciSCKqKcLS",
"item_price_id": "silver-usd",
"note": "Day 1 usage from __test__XpbBrciSCKqKUcN",
"object": "usage",
"quantity": "5",
"resource_version": 1601708189381,
"subscription_id": "__test__XpbBrciSCKqKXhP",
"updated_at": 1601708189,
"usage_date": 1601718989
}API Index URL
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. Note: If
usage_date corresponds to a time already invoiced, then it is stored but never invoiced unless the invoice is regenerated. The id of the item price to which this usage belongs. The item price must be a part of the subscription or should have been part of it historically.
When the usage has been invoiced, this is the
id of the invoice. This is cleared when the invoice is voided or deleted. When the usage has been invoiced, this is the
id of the invoice.line_item that the usage is for. This is cleared when the invoice is voided or deleted. A note for this usage record. This note is not displayed on any customer-facing document or interface such as invoice PDFs or Hosted Pages.
Create a usage ¶
Creates a usage record for an item price in a subscription. The item price must belong to a metered item.
Max Usages
The maximum number of usages that can be recorded for the entire lifetime of a subscription is 5000. Contact Support if you want this limit to be increased for your site.
Sample Response [ JSON ]
URL Format POST
Input Parameters
The id of the item price to which this usage belongs. The item price must be a part of the subscription or should have been part of it historically.
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. Note: If
usage_date corresponds to a time already invoiced, then it is stored but never invoiced unless the invoice is regenerated. A note for this usage record. This note is not displayed on any customer-facing document or interface such as invoice PDFs or Hosted Pages.
Returns
Resource object representing usage
Retrieve a usage ¶
Retrieves a usage record of a specific subscription.
Sample Response [ JSON ]
URL Format GET
Input Parameters
Returns
Resource object representing usage
Delete a usage ¶
Deletes a usage record. This operation cannot be invoked for a usage record that has been invoiced.
Sample Response [ JSON ]
URL Format POST
Input Parameters
Returns
Resource object representing usage
List usages ¶
Retrieves the list of usages.
Sample Response [ JSON ]
URL Format GET
Input Parameters
Sorts based on the specified attribute.
Supported attributes : usage_date, updated_at
Supported sort-orders : asc, desc
Example → sort_by[asc] = "usage_date"
This will sort the result based on the 'usage_date' attribute in ascending(earliest first) order.
Filter Params
For operator usages, see the Pagination and Filtering section.
The id of the subscription to which this usage record belongs.
Supported operators : is, is_not, starts_with
Example → subscription_id[is] = "active2"
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. Note: If
usage_date corresponds to a time already invoiced, then it is stored but never invoiced unless the invoice is regenerated. Supported operators : after, before, on, between
Example → usage_date[after] = "1601220958"
The id of the item price to which this usage belongs. The item price must be a part of the subscription or should have been part of it historically.
Supported operators : is, is_not, starts_with
Example → item_price_id[is] = "sprout"
When the usage has been invoiced, this is the
id of the invoice. This is cleared when the invoice is voided or deleted. Supported operators : is, is_not, starts_with, is_present
Example → invoice_id[is] = "null"
Returns
Resource object representing usage
This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter `offset`.
Retrieve Usages for an Invoice as PDF ¶
Retrieves usages record for an invoice in PDF file format.
Sample Response [ JSON ]
URL Format POST
Input Parameters
Returns
Resource object representing download