You are viewing the documentation for Chargebee API V2. If you're using the older version (V1), click here.

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
optional, string, max chars=100
A unique and immutable id for the usage. If not provided, it is autogenerated.
usage_date
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.
subscription_id
string, max chars=100
The id of the subscription to which this usage record belongs.
item_price_id
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.
invoice_id
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.
line_item_id
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.
quantity
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 values are
admin_consoleOperation made through the Chargebee admin UI.apiOperation made through the API.bulk_operationOperation that are triggerd through bulk operation.
note
optional, string, max chars=500
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.
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
timestamp(UTC) in seconds
Timestamp indicating when the item was created.

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
optional, string, max chars=100
A unique and immutable id for the usage. If not provided, it is autogenerated.
item_price_id
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.
quantity
required, string, max chars=40
The quantity specified for this usage record.
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.
Note: If usage_date corresponds to a time already invoiced, then it is stored but never invoiced unless the invoice is regenerated.
note
optional, string, max chars=500
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.
always returned
Resource object representing usage.

Retrieves a usage record of a specific subscription.

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
required, string, max chars=100
A unique and immutable id for the usage. If not provided, it is autogenerated.
always returned
Resource object representing usage.

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
required, string, max chars=100
A unique and immutable id for the usage. If not provided, it is autogenerated.
always returned
Resource object representing usage.
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
optional, integer, default=10, min=1, max=100
The number of resources to be returned.
offset
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.
sort_by[<sort-order>]
optional, string filter
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.
Filter Params
For operator usages, see the Pagination and Filtering section.
id[<operator>]
optional, string filter
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"
subscription_id[<operator>]
optional, string filter
The id of the subscription to which this usage record belongs.
Supported operators : is, is_not, starts_with

Example subscription_id[is] = "active2"
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.
Supported operators : after, before, on, between

Example usage_date[after] = "1601220958"
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.
Supported operators : is, is_not, starts_with

Example item_price_id[is_not] = "sprout"
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.
Supported operators : is, is_not, starts_with, is_present

Example invoice_id[is_not] = "null"
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"
always returned
Resource object representing usage.
next_offset
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.

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
optional, enumerated string, default=attachment
Determines the pdf should be rendered as inline or attachment in the browser.
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]
required, string, max chars=50
The invoice number. Acts as a identifier for invoice and typically generated sequentially.
always returned
Resource object representing download.