Usages

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

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

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

optional, string, max chars=100
A unique and immutable id for the usage. If not provided, it is autogenerated.

usage_date

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

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

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

Try in API Explorer

Only for Java

copy full code

Click to Copy

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

Create an usage

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[]

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

always returned
Resource object representing usage

Retrieves a usage record of a specific subscription.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__XpbBrciSCKqL28j/usages \
     -u {site_api_key}:\
     -d id="usage_XpbBrciSCKqL5vm"

copy

Click to Copy

Retrieve an usage

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

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__XpbBrciSCKqKhtV/delete_usage \
     -u {site_api_key}:\
     -d id="usage_XpbBrciSCKqKlkY"

copy

Click to Copy

Delete an usage

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

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/usages \
     -G  \
     -u {site_api_key}:\
     --data-urlencode "subscription_id[is]"="__test__XpbBrciSCKqKsNb"

copy

Click to Copy

List usages

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, updated_at
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"

updated_at[<operator>]

optional, timestamp(UTC) in seconds filter

Supported operators : after, before, on, between

Example → updated_at[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] = "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

Try in API Explorer

Only for Java

copy full code

Click to Copy

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

Retrieve usages for an invoice as pdf

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

invoice

Parameters for invoice
pass parameters as invoice[<param name>]

invoice[id]

required, string, max chars=50

download

always returned
Resource object representing download

Invoicing Metered Item Prices

Sample usage [ JSON ]

API Index URL GET

Model Class

Usage attributes

Consent Fields for Usage

Custom Fields for Usage

Create a usage ¶

Notes

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Retrieve a usage ¶

Notes

Sample Response [ JSON ]

URL Format GET

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Delete a usage ¶

Notes

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

List usages ¶

Notes

Sample Response [ JSON ]

URL Format GET

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Retrieve Usages for an Invoice as PDF ¶

Notes

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL