Sign inGet started →
Help DocsAPI Guides

Subscription Items

In Lemon Squeezy, a subscription item is an object that links a price to a subscription and also contains quantity information.

A subscription item belongs to a Subscription and a Price and can have many Usage records.

The subscription item object

Attributes

subscription_id

The ID of the Subscription associated with this subscription item.

price_id

The ID of the Price associated with this subscription item.

quantity

A positive integer representing the unit quantity of this subscription item.

Will be 0 if the related subscription product/variant has usage-based billing enabled.

is_usage_based

A boolean value indicating whether the related subscription product/variant has usage-based billing enabled.

created_at

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

updated_at

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

Subscription item object

{ "type": "subscription-items", "id": "1", "attributes": { "subscription_id": 1, "price_id": 1, "quantity": 1, "is_usage_based": false, "created_at": "2023-07-18T12:16:24.000000Z", "updated_at": "2023-07-18T12:16:24.000000Z" }, "relationships": { "subscription": { "links": { "related": "https://api.lemonsqueezy.com/v1/subscription-items/1/subscription", "self": "https://api.lemonsqueezy.com/v1/subscription-items/1/relationships/subscription" } }, "price": { "links": { "related": "https://api.lemonsqueezy.com/v1/subscription-items/1/price", "self": "https://api.lemonsqueezy.com/v1/subscription-items/1/relationships/price" } }, "usage-records": { "links": { "related": "https://api.lemonsqueezy.com/v1/subscription-items/1/usage-records", "self": "https://api.lemonsqueezy.com/v1/subscription-items/1/relationships/usage-records" } } }, "links": { "self": "https://api.lemonsqueezy.com/v1/subscription-items/1" } }

Retrieve a subscription item

Retrieves the subscription item with the given ID.

GET /v1/subscription-items/:id

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

Returns

Returns a subscription item object.

Response

{ "jsonapi": { "version": "1.0" }, "links": { "self": "https://api.lemonsqueezy.com/v1/subscription-item/1" }, "data": { "type": "subscription-items", "id": "1", "attributes": { "subscription_id": 1, "price_id": 1, "quantity": 1, "is_usage_based": false, "created_at": "2023-07-18T12:16:24.000000Z", "updated_at": "2023-07-18T12:16:24.000000Z" }, "relationships": { "subscription": { "links": { "related": "https://api.lemonsqueezy.com/v1/subscription-items/1/subscription", "self": "https://api.lemonsqueezy.com/v1/subscription-items/1/relationships/subscription" } }, "price": { "links": { "related": "https://api.lemonsqueezy.com/v1/subscription-items/1/price", "self": "https://api.lemonsqueezy.com/v1/subscription-items/1/relationships/price" } }, "usage-records": { "links": { "related": "https://api.lemonsqueezy.com/v1/subscription-items/1/usage-records", "self": "https://api.lemonsqueezy.com/v1/subscription-items/1/relationships/usage-records" } } }, "links": { "self": "https://api.lemonsqueezy.com/v1/subscription-items/1" } } }

Update a subscription item

Update a subscription item.

Note: this endpoint is only used with quantity-based billing. If the related subscription's product/variant has usage-based billing enabled, this endpoint will return a 422 Unprocessable Entity response.

Attributes

quantity

The unit quantity of the subscription.

invoice_immediately

If true, any updates to the subscription will be charged immediately. A new prorated invoice will be generated and payment attempted. Defaults to false. Note that this will be overridden by the disable_prorations option if used.

Read about proration in the Developer Guide.

disable_prorations

If true, no proration will be charged and the customer will simply be charged the new price at the next renewal. Defaults to false. Note that this will override the invoice_immediately option if used.

Read about proration in the Developer Guide.

PATCH /v1/subscription-items/:id

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

Returns

Returns a subscription item object.

Response

{ "jsonapi": { "version": "1.0" }, "links": { "self": "https://api.lemonsqueezy.com/v1/subscription-item/1" }, "data": { "type": "subscription-items", "id": "1", "attributes": { "subscription_id": 1, "price_id": 1, "quantity": 10, "is_usage_based": false, "created_at": "2023-07-18T12:16:24.000000Z", "updated_at": "2023-07-18T12:23:18.000000Z" }, "relationships": { "subscription": { "links": { "related": "https://api.lemonsqueezy.com/v1/subscription-items/1/subscription", "self": "https://api.lemonsqueezy.com/v1/subscription-items/1/relationships/subscription" } }, "price": { "links": { "related": "https://api.lemonsqueezy.com/v1/subscription-items/1/price", "self": "https://api.lemonsqueezy.com/v1/subscription-items/1/relationships/price" } }, "usage-records": { "links": { "related": "https://api.lemonsqueezy.com/v1/subscription-items/1/usage-records", "self": "https://api.lemonsqueezy.com/v1/subscription-items/1/relationships/usage-records" } } }, "links": { "self": "https://api.lemonsqueezy.com/v1/subscription-items/1" } } }

List all subscription items

Returns a paginated list of subscription items.

Parameters

subscription_id

Only return subscription items belonging to a subscription with this ID.

price_id

Only return subscription items belonging to a price with this ID.

GET /v1/subscription-items

curl "https://api.lemonsqueezy.com/v1/subscription-items" -H 'Accept: application/vnd.api+json' -H 'Content-Type: application/vnd.api+json' -H 'Authorization: Bearer {api_key}'
curl "https://api.lemonsqueezy.com/v1/subscription-items?filter[subscription_id]=6" -H 'Accept: application/vnd.api+json' -H 'Content-Type: application/vnd.api+json' -H 'Authorization: Bearer {api_key}'

Returns

Returns a paginated list of subscription item 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/subscription-items?page%5Bnumber%5D=1&page%5Bsize%5D=10&sort=-created_at", "last": "https://api.lemonsqueezy.com/v1/subscription-items?page%5Bnumber%5D=1&page%5Bsize%5D=10&sort=-created_at" }, "data": [ { "type": "subscription-items", "id": "1", "attributes": { "subscription_id": 1, "price_id": 1, "quantity": 1, "is_usage_based": false, "created_at": "2023-07-18T12:16:24.000000Z", "updated_at": "2023-07-18T12:16:24.000000Z" }, "relationships": { "subscription": { "links": { "related": "https://api.lemonsqueezy.com/v1/subscription-items/1/subscription", "self": "https://api.lemonsqueezy.com/v1/subscription-items/1/relationships/subscription" } }, "price": { "links": { "related": "https://api.lemonsqueezy.com/v1/subscription-items/1/price", "self": "https://api.lemonsqueezy.com/v1/subscription-items/1/relationships/price" } }, "usage-records": { "links": { "related": "https://api.lemonsqueezy.com/v1/subscription-items/1/usage-records", "self": "https://api.lemonsqueezy.com/v1/subscription-items/1/relationships/usage-records" } } }, "links": { "self": "https://api.lemonsqueezy.com/v1/subscription-items/1" } }, {...}, {...}, ] }

Retrieve a subscription item's current usage

Retrieves the unit usage for a subscription item for the current billing period.

Note: this endpoint is only for subscriptions with usage-based billing enabled. It will return a 404 Not Found response if the related subscription product/variant does not have usage-based billing enabled.

GET /v1/subscription-items/:id/current-usage

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

Returns

Returns a meta object containing usage information.

period_start

An ISO 8601 formatted date-time string indicating the start of the billing period.

period_end

An ISO 8601 formatted date-time string indicating the end of the billing period.

quantity

A positive integer representing the usage total.

interval_unit

The interval unit of the subscription's variant. One of

  • day
  • week
  • month
  • year

interval_quantity

The interval count of the subscription's variant.

For example, a subscription item with interval_unit=month and interval_quantity=3 would mean the subscription renews every a three months.

Response

{ "jsonapi": { "version": "1.0" }, "meta": { "period_start": "2023-08-10T13:08:16+00:00", "period_end": "2023-09-10T13:03:16+00:00", "quantity": 5, "interval_unit": "month", "interval_quantity": 1 } }