Usages

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 ]

{"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

usage

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 ]

{"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.

usage

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 ]

{"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.

usage

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 ]

{"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] = "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] = "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"

usage

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 ]

{"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 browserinlinePDF 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.

download

always returned
Resource object representing download

Invoicing Metered Item Prices

Sample usage [ JSON ]

API Index URL GET

Usage attributes

Create a usage¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Retrieve a usage¶

Sample Response [ JSON ]

URL Format GET

Input Parameters

Returns

Delete a usage¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

List usages¶

Sample Response [ JSON ]

URL Format GET

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Retrieve Usages for an Invoice as PDF¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns