API Version
Product Catalog
Library

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

Model Class

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 UIapiOperation made through the APIbulk_operationOperation that are triggerd through bulk operation.
Show all values[+]
note
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.
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.
id id
optional, string, max chars=100
A unique and immutable id for the usage. If not provided, it is autogenerated.
usage_date 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 subscription_id
string, max chars=100
The id of the subscription to which this usage record belongs.
item_price_id 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 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 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 quantity
string, max chars=40
The quantity specified for this usage record.
source source
optional, enumerated string
The source from which the usage record was created.
note note
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.
resource_version 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 updated_at
optional, timestamp(UTC) in seconds
Timestamp indicating when this usage resource was last updated.
created_at 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.

Notes

Sample Request
# Create an usage
curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__XpbBrciSCKqKXhP/usages \
     -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
Click to Copy

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

Method

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 note is not displayed on any customer-facing document or interface such as invoice PDFs or Hosted Pages.
usage usage
always returned
Resource object representing usage

Sample admin console URL

https://{site}.chargebee.com/admin-console/usages/123x

Retrieves a usage record of a specific subscription.

Notes

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
Click to Copy

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

Method

id[]
required, string, max chars=100
A unique and immutable id for the usage. If not provided, it is autogenerated.
usage usage
always returned
Resource object representing usage

Sample admin console URL

https://{site}.chargebee.com/admin-console/usages/123x

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

Notes

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

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

Method

id[]
required, string, max chars=100
A unique and immutable id for the usage. If not provided, it is autogenerated.
usage usage
always returned
Resource object representing usage

Sample admin console URL

https://{site}.chargebee.com/admin-console/usages/123x
Retrieves the list of usages.

Notes

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
Click to Copy

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

Method

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. Possible values are :
Supported operators : is, is_not, starts_with

Example id[is] = "usage_lsfja24411"
id[is][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
id[is_not][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
id[starts_with][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
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[is][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
subscription_id[is_not][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
subscription_id[starts_with][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
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[after][operator]
optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :

Example
usage_date[before][operator]
optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :

Example
usage_date[on][operator]
optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :

Example
usage_date[between][operator]
optional, string filter
Possible values are :
Supported operators :

Example
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[is][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
item_price_id[is_not][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
item_price_id[starts_with][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
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[is][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
invoice_id[is_not][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
invoice_id[starts_with][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
invoice_id[is_present][operator]
optional, enumerated string filter
Possible values are : true, false
Supported operators :

Example
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[is][operator]
optional, enumerated string filter
Possible values are : admin_console, api, bulk_operation
Supported operators :

Example
source[is_not][operator]
optional, enumerated string filter
Possible values are : admin_console, api, bulk_operation
Supported operators :

Example
source[in][operator]
optional, string filter
Possible values are :
Supported operators :

Example
source[not_in][operator]
optional, string filter
Possible values are :
Supported operators :

Example
usage usage
always returned
Resource object representing usage
next_offset 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`.

Sample admin console URL

https://{site}.chargebee.com/admin-console/usages/123x

Retrieves usages record for an invoice in PDF file format.

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"
copy
Click to Copy

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

Method

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 browserinlinePDF is rendered as inline in the browser
Show all values[+]
invoice[id]
required, string, max chars=50
download download
always returned
Resource object representing download

Sample admin console URL

https://{site}.chargebee.com/admin-console/usages/123x