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 typeplan 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.
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. Note: If usage_date corresponds to a time already invoiced, then it is stored but never invoiced unless the invoice is regenerated.
string, max chars=100 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.
optional, string, max chars=100 When the usage has been invoiced, this is the id of the invoice. This is cleared when the invoice is voided or deleted.
optional, string, max chars=100 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.
optional, enumerated string The source from which the usage record was created.
Possible values are
admin_consoleOperation made through the Chargebee admin UIapiOperation made through the APIbulk_operationOperation that are triggerd through bulk operation.
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 or Hosted Pages.
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.
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. Note: If usage_date corresponds to a time already invoiced, then it is stored but never invoiced unless the invoice is regenerated.
string, max chars=100 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.
optional, string, max chars=100 When the usage has been invoiced, this is the id of the invoice. This is cleared when the invoice is voided or deleted.
optional, string, max chars=100 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.
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 or Hosted Pages.
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.
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.
This API is not enabled for live sites by default. Please contact
support to get this enabled.
required, string, max chars=100 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.
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. Note: If usage_date corresponds to a time already invoiced, then it is stored but never invoiced unless the invoice is regenerated.
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 or Hosted Pages.
optional, string, max chars=1000 Determines your position in the list for pagination. To ensure that the next page is retrieved correctly, always set offset to the value of next_offset obtained in the previous iteration of the API call.
optional, string filter A unique and immutable id for the usage. If not provided, it is autogenerated.Possible values are : Supported operators : is, is_not, starts_with
Example →id[is] = "usage_lsfja24411"
+
id
A unique and immutable id for the usage. If not provided, it is autogenerated. pass parameters as id[<param name>][<operator>]
id[is][operator]
id[is][operator]
optional, string, min chars=1 filter Possible values are : Supported operators :
Example →
id[is_not][operator]
id[is_not][operator]
optional, string, min chars=1 filter Possible values are : Supported operators :
Example →
id[starts_with][operator]
id[starts_with][operator]
optional, string, min chars=1 filter Possible values are : Supported operators :
Example →
subscription_id[<operator>]
subscription_id[<operator>]
required, string filter The id of the subscription to which this usage record belongs.Possible values are : Supported operators : is, is_not, starts_with
Example →subscription_id[is] = "active2"
+
subscription_id
The id of the subscription to which this usage record belongs. pass parameters as subscription_id[<param name>][<operator>]
subscription_id[is][operator]
subscription_id[is][operator]
optional, string, min chars=1 filter Possible values are : Supported operators :
Example →
subscription_id[is_not][operator]
subscription_id[is_not][operator]
optional, string, min chars=1 filter Possible values are : Supported operators :
Example →
subscription_id[starts_with][operator]
subscription_id[starts_with][operator]
optional, string, min chars=1 filter Possible values are : Supported operators :
Example →
usage_date[<operator>]
usage_date[<operator>]
optional, timestamp(UTC) in seconds filter 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.Possible values are : Supported operators : after, before, on, between
Example →usage_date[after] = "1601220958"
+
usage_date
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. pass parameters as usage_date[<param name>][<operator>]
usage_date[after][operator]
usage_date[after][operator]
optional, timestamp(UTC) in seconds filter Possible values are : Supported operators :
Example →
usage_date[before][operator]
usage_date[before][operator]
optional, timestamp(UTC) in seconds filter Possible values are : Supported operators :
Example →
usage_date[on][operator]
usage_date[on][operator]
optional, timestamp(UTC) in seconds filter Possible values are : Supported operators :
Example →
usage_date[between][operator]
usage_date[between][operator]
optional, string filter Possible values are : Supported operators :
Example →
item_price_id[<operator>]
item_price_id[<operator>]
optional, string filter 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.Possible values are : Supported operators : is, is_not, starts_with
Example →item_price_id[is] = "sprout"
+
item_price_id
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. pass parameters as item_price_id[<param name>][<operator>]
item_price_id[is][operator]
item_price_id[is][operator]
optional, string, min chars=1 filter Possible values are : Supported operators :
Example →
item_price_id[is_not][operator]
item_price_id[is_not][operator]
optional, string, min chars=1 filter Possible values are : Supported operators :
Example →
item_price_id[starts_with][operator]
item_price_id[starts_with][operator]
optional, string, min chars=1 filter Possible values are : Supported operators :
Example →
invoice_id[<operator>]
invoice_id[<operator>]
optional, string filter When the usage has been invoiced, this is the id of the invoice. This is cleared when the invoice is voided or deleted.Possible values are : Supported operators : is, is_not, starts_with, is_present
Example →invoice_id[is] = "null"
+
invoice_id
When the usage has been invoiced, this is the id of the invoice. This is cleared when the invoice is voided or deleted. pass parameters as invoice_id[<param name>][<operator>]
invoice_id[is][operator]
invoice_id[is][operator]
optional, string, min chars=1 filter Possible values are : Supported operators :
Example →
invoice_id[is_not][operator]
invoice_id[is_not][operator]
optional, string, min chars=1 filter Possible values are : Supported operators :
Example →
invoice_id[starts_with][operator]
invoice_id[starts_with][operator]
optional, string, min chars=1 filter Possible values are : Supported operators :
Example →
invoice_id[is_present][operator]
invoice_id[is_present][operator]
optional, enumerated string filter Possible values are : true, false Supported operators :
Example →
source[<operator>]
source[<operator>]
optional, enumerated string filter The source from which the usage record was created. Possible values are : admin_console, api, bulk_operation Supported operators : is, is_not, in, not_in
Example →source[is] = "api"
+
source
The source from which the usage record was created. pass parameters as source[<param name>][<operator>]
source[is][operator]
source[is][operator]
optional, enumerated string filter Possible values are : admin_console, api, bulk_operation Supported operators :
Example →
source[is_not][operator]
source[is_not][operator]
optional, enumerated string filter Possible values are : admin_console, api, bulk_operation Supported operators :
Example →
source[in][operator]
source[in][operator]
optional, string filter Possible values are : Supported operators :
Example →
source[not_in][operator]
source[not_in][operator]
optional, string filter Possible values are : Supported operators :
always returned optional, string, max chars=1000 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`.
Retrieves usages record for an invoice in PDF file format.
This API is not enabled for live sites by default. Please contact
support to get this enabled.
Notes
Sample Request
# Retrieve Usages for an Invoice as PDF
curl https://{site}.chargebee.com/api/v2/usages/pdf \
-u {site_api_key}:\
-d disposition_type="INLINE" \
-d invoice[id]="__demo_inv__1"