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
Retrieve a subscription item
Retrieves the subscription item with the given ID.
GET /v1/subscription-items/:id
Returns
Returns a subscription item object.
Response
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
Returns
Returns a subscription item object.
Response
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
Returns
Returns a paginated list of subscription item objects ordered by created_at
(descending).
Response
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
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.