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 GET

https://{site}.chargebee.com/api/v2/usages
id
A unique and immutable id for the usage. If not provided, it is autogenerated.
optional, string, max chars=100
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.
timestamp(UTC) in seconds
subscription_id
The id of the subscription to which this usage record belongs.
string, max chars=100
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.
string, max chars=100
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.
optional, string, max chars=100
line_item_id
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=100
quantity
The quantity specified for this usage record.
string, max chars=40
source
The source from which the usage record was created.
optional, enumerated string
Possible values are
admin_consoleOperation made through the Admin Console.apiOperation made through the API.bulk_operationOperation that are triggerd through bulk operation.
note
A note for this usage record. This appears against the usage on the Chargebee UI. This note is not displayed on any customer-facing document or interface such as invoice PDFs or Hosted Pages.
optional, string, max chars=500
resource_version
Version number of this resource. Each update of this resource results in incremental change of this number. This attribute will be present only if the resource has been updated after 2016-09-28.
optional, long
updated_at
Timestamp indicating when this usage resource was last updated.
optional, timestamp(UTC) in seconds
created_at
Timestamp indicating when the item was created.
timestamp(UTC) in seconds

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 Request
# Create an usage
curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__XpbBrciSCKqKXhP/usages \
     -X POST  \
     -u {site_api_key}:\
     -d item_price_id="silver-usd" \
     -d usage_date=1601718989 \
     -d note="Day 1 usage from __test__XpbBrciSCKqKUcN" \
     -d quantity="5"
copy
# Create an usage
curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__XpbBrciSCKqKXhP/usages \
     -X POST  \
     -u {site_api_key}:\
     -d item_price_id="silver-usd" \
     -d usage_date=1601718989 \
     -d note="Day 1 usage from __test__XpbBrciSCKqKUcN" \
     -d quantity="5"

Sample Response [ JSON ]

Show more...
{"usage": { "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 }}

URL Format POST

https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/usages
id
A unique and immutable id for the usage. If not provided, it is autogenerated.
optional, string, max chars=100
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.
required, string, max chars=100
quantity
The quantity specified for this usage record.
required, string, max chars=40
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.
required, timestamp(UTC) in seconds
note
A note for this usage record. This appears against the usage on the Chargebee UI. This note is not displayed on any customer-facing document or interface such as invoice PDFs or Hosted Pages.
optional, string, max chars=500
Resource object representing usage.
always returned
Sample Request
# Retrieve an usage
curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__XpbBrciSCKqL28j/usages \
     -u {site_api_key}:\
     -d id="usage_XpbBrciSCKqL5vm"
copy
# Retrieve an usage
curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__XpbBrciSCKqL28j/usages \
     -u {site_api_key}:\
     -d id="usage_XpbBrciSCKqL5vm"

Sample Response [ JSON ]

Show more...
{"usage": { "created_at": 1601708191, "id": "usage_XpbBrciSCKqL5vm", "item_price_id": "silver-usd", "note": "Day 1 usage from __test__XpbBrciSCKqKzeh", "object": "usage", "quantity": "5", "resource_version": 1601708191233, "subscription_id": "__test__XpbBrciSCKqL28j", "updated_at": 1601708191, "usage_date": 1601718991 }}

URL Format GET

https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/usages
id
A unique and immutable id for the usage. If not provided, it is autogenerated.
required, string, max chars=100
Resource object representing usage.
always returned

Deletes a usage record. This operation cannot be invoked for a usage record that has been invoiced.

Sample Request
# Delete an usage
curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__XpbBrciSCKqKhtV/delete_usage \
     -X POST  \
     -u {site_api_key}:\
     -d id="usage_XpbBrciSCKqKlkY"
copy
# Delete an usage
curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__XpbBrciSCKqKhtV/delete_usage \
     -X POST  \
     -u {site_api_key}:\
     -d id="usage_XpbBrciSCKqKlkY"

Sample Response [ JSON ]

Show more...
{"usage": { "created_at": 1601708189, "id": "usage_XpbBrciSCKqKlkY", "item_price_id": "silver-usd", "note": "Day 1 usage from __test__XpbBrciSCKqKeoT", "object": "usage", "quantity": "5", "resource_version": 1601708189992, "subscription_id": "__test__XpbBrciSCKqKhtV", "updated_at": 1601708189, "usage_date": 1601718989 }}

URL Format POST

https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/delete_usage
id
A unique and immutable id for the usage. If not provided, it is autogenerated.
required, string, max chars=100
Resource object representing usage.
always returned
Retrieves the list of usages.
Sample Request
# List usages
curl  https://{site}.chargebee.com/api/v2/usages \
     -G  \
     -u {site_api_key}:\
     --data-urlencode subscription_id[is]="__test__XpbBrciSCKqKsNb"
copy
# List usages
curl  https://{site}.chargebee.com/api/v2/usages \
     -G  \
     -u {site_api_key}:\
     --data-urlencode subscription_id[is]="__test__XpbBrciSCKqKsNb"

Sample Response [ JSON ]

Show more...
{"list": [ {"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 }}, {..} ]}

URL Format GET

https://{site}.chargebee.com/api/v2/usages
limit
The number of resources to be returned.
optional, integer, default=10, min=1, max=100
offset
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, max chars=1000
sort_by[<sort-order>]
Sorts based on the specified attribute.
Supported attributes : usage_date
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.
optional, string filter
Filter Params
For operator usages, see the Pagination and Filtering section.
id[<operator>]
A unique and immutable id for the usage. If not provided, it is autogenerated.
Supported operators : is, is_not, starts_with

Example id[is_not] = "usage_lsfja24411"
optional, string filter
subscription_id[<operator>]
The id of the subscription to which this usage record belongs.
Supported operators : is, is_not, starts_with

Example subscription_id[is] = "active2"
optional, string filter
usage_date[<operator>]
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[on] = "1601220958"
optional, timestamp(UTC) in seconds filter
item_price_id[<operator>]
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"
optional, string filter
invoice_id[<operator>]
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"
optional, string filter
source[<operator>]
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"
optional, enumerated string filter
Resource object representing usage.
always returned
next_offset
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”.
optional, string, max chars=1000
Sample Request
# Retrieve Usages for an Invoice as PDF
curl  https://{site}.chargebee.com/api/v2/usages/pdf \
     -X POST  \
     -u {site_api_key}:\
     -d invoice[id]="__demo_inv__1" \
     -d disposition_type="inline"
copy
# Retrieve Usages for an Invoice as PDF
curl  https://{site}.chargebee.com/api/v2/usages/pdf \
     -X POST  \
     -u {site_api_key}:\
     -d invoice[id]="__demo_inv__1" \
     -d disposition_type="inline"

Sample Response [ JSON ]

Show more...
{"download": { "download_url": "https://cb-local-downloads.s3.amazonaws.com/yourapp/usage/__test__KyVnOySLTs2AP27.pdf?response-content-disposition=inline%3Bfilename%3Dyourapp%2Fusage%2F__test__KyVnOySLTs2AP27.pdf&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20210108T061943Z&X-Amz-SignedHeaders=host&X-Amz-Expires=599&X-Amz-Credential=AKIAJI4SN7ONHAOGLOGA%2F20210108%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=3648b8dadb4fcafea3375bf5f9b116e5cbdb295b8428965810b6533417b04b88", "object": "download", "valid_till": 1610087383 }}

URL Format POST

https://{site}.chargebee.com/api/v2/usages/pdf
disposition_type
Determines the pdf should be rendered as inline or attachment in the browser.
optional, enumerated string, default=attachment
Possible values are
attachmentpdf is rendered as attachment in the browser.inlinepdf is rendered as inline in the browser.
+
invoice
Parameters for invoice
pass parameters as invoice[<param name>]
invoice[id]
The invoice number. Acts as a identifier for invoice and typically generated sequentially.
required, string, max chars=50
Resource object representing download.
always returned