Sign inGet started →
Help DocsAPI Guides

Usage Records

In Lemon Squeezy, a usage record is used to report the amount of usage for a subscription item when the product has usage-based billing enabled.

A usage record belongs to a Subscription Item.

The usage record object

Attributes

subscription_item_id

The ID of the subscription item this usage record belongs to.

quantity

A positive integer representing the usage to be reported.

action

The type of record. One of

  • increment - The provided quantity was added to existing records for the current billing period.
  • set - The provided quantity was set as the total usage for the current billing period.

created_at

An ISO 8601 formatted date-time string indicating when the object was created.

updated_at

An ISO 8601 formatted date-time string indicating when the object was last updated.

Usage record object

{ "type": "usage-records", "id": "1", "attributes": { "subscription_item_id": 1, "quantity": 5, "action": "increment", "created_at": "2023-07-24T14:44:38.000000Z", "updated_at": "2023-07-24T14:44:38.000000Z" } }

Create a usage record

Create a usage record.

Attributes

quantity

A positive integer representing the usage to be reported.

action

The type of record. One of

  • increment - Add the provided quantity to existing records for the current billing period.
  • set - Set the quantity for the current billing period to the provided quantity.

Defaults to increment if omitted.

Note: increment should only be used alongside the "Sum of usage during period" aggregation setting. set should be only used alongside "Most recent usage during a period" and "Most recent usage" aggregation settings. Read more about aggregation settings.

Relationships

subscription_item

The subscription item this usage record belongs to.

POST /v1/usage-records

curl -X "POST" "https://api.lemonsqueezy.com/v1/usage-records" -H 'Accept: application/vnd.api+json' -H 'Content-Type: application/vnd.api+json' -H 'Authorization: Bearer {api_key}' -d $'{ "data": { "type": "usage-records", "attributes": { "quantity": 5 }, "relationships": { "subscription-item": { "data": { "type": "subscription-items", "id": "1" } } } } }'

Returns

Returns a usage record object.

Response

{ "jsonapi": { "version": "1.0" }, "links": { "self": "https://api.lemonsqueezy.com/v1/usage-records/1" }, "data": { "type": "usage-records", "id": "1", "attributes": { "subscription_item_id": 1, "quantity": 5, "action": "increment", "created_at": "2023-07-24T14:44:38.000000Z", "updated_at": "2023-07-24T14:44:38.000000Z" }, "relationships": { "subscription-item": { "links": { "related": "https://api.lemonsqueezy.com/v1/usage-records/1/subscription-item", "self": "https://api.lemonsqueezy.com/v1/usage-records/1/relationships/subscription-item" } } }, "links": { "self": "https://api.lemonsqueezy.com/v1/usage-records/1" } } }

Retrieve a usage record

Retrieves the usage record with the given ID.

Note: to retrieve the current total usage for a subscription, use the subscription item current usage endpoint.

GET /v1/usage-records/:id

curl "https://api.lemonsqueezy.com/v1/usage-records/1" -H 'Accept: application/vnd.api+json' -H 'Content-Type: application/vnd.api+json' -H 'Authorization: Bearer {api_key}'

Returns

Returns a usage record object.

Response

{ "jsonapi": { "version": "1.0" }, "links": { "self": "https://api.lemonsqueezy.com/v1/usage-records/1" }, "data": { "type": "usage-records", "id": "1", "attributes": { "subscription_item_id": 1, "quantity": 5, "action": "increment", "created_at": "2023-07-24T14:44:38.000000Z", "updated_at": "2023-07-24T14:44:38.000000Z" }, "relationships": { "subscription-item": { "links": { "related": "https://api.lemonsqueezy.com/v1/usage-records/1/subscription-item", "self": "https://api.lemonsqueezy.com/v1/usage-records/1/relationships/subscription-item" } } }, "links": { "self": "https://api.lemonsqueezy.com/v1/usage-records/1" } } }

List all usage records

Returns a paginated list of usage records.

Parameters

subscription_item_id

Only return usage records belonging to the subscription item with this ID.

GET /v1/usage-records

curl "https://api.lemonsqueezy.com/v1/usage-records" \ -H 'Accept: application/vnd.api+json' \ -H 'Content-Type: application/vnd.api+json' \ -H 'Authorization: Bearer {api_key}'
curl "https://api.lemonsqueezy.com/v1/usage-records?filter[subscription_item_id]=1" \ -H 'Accept: application/vnd.api+json' \ -H 'Content-Type: application/vnd.api+json' \ -H 'Authorization: Bearer {api_key}'

Returns

Returns a paginated list of usage record objects ordered by created_at (descending).

Response

{ "meta": { "page": { "currentPage": 1, "from": 1, "lastPage": 1, "perPage": 10, "to": 10, "total": 10 } }, "jsonapi": { "version": "1.0" }, "links": { "first": "https://api.lemonsqueezy.com/v1/usage-records?page%5Bnumber%5D=1&page%5Bsize%5D=10&sort=-created_at", "last": "https://api.lemonsqueezy.com/v1/usage-records?page%5Bnumber%5D=1&page%5Bsize%5D=10&sort=-created_at", }, "data": [ { "type": "usage-records", "id": "1", "attributes": { "subscription_item_id": 1, "quantity": 5, "action": "increment", "created_at": "2023-07-24T14:44:38.000000Z", "updated_at": "2023-07-24T14:44:38.000000Z" }, "relationships": { "subscription-item": { "links": { "related": "https://api.lemonsqueezy.com/v1/usage-records/1/subscription-item", "self": "https://api.lemonsqueezy.com/v1/usage-records/1/relationships/subscription-item" } } }, "links": { "self": "https://api.lemonsqueezy.com/v1/usage-records/1" } }, {...}, {...}, ] }