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 UsageJSON
Usages attributes
A unique and immutable id for the usage. If not provided, it is autogenerated.
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 subscription to which this usage record belongs.
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
.
The source from which the usage record was created.
Operation made through the Chargebee admin UI
Operation made through the API
Operation that are triggerd through bulk operation.
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 .
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.
Timestamp indicating when this usage resource was last updated.