Subscriptions
In Lemon Squeezy, a subscription is created when a subscription product is purchased and will bill the customer on a recurring basis.
A subscription belongs to a Store and is associated with a Customer, an Order, an Order Item, a Product, a Variant, Subscription invoices and Subscription items.
The subscription object
Attributes
store_id
The ID of the store this subscription belongs to.
customer_id
The ID of the customer this subscription belongs to.
order_id
The ID of the order associated with this subscription.
order_item_id
The ID of the order item associated with this subscription.
product_id
The ID of the product associated with this subscription.
variant_id
The ID of the variant associated with this subscription.
product_name
The name of the product.
variant_name
The name of the variant.
user_name
The full name of the customer.
user_email
The email address of the customer.
status
The status of the subscription. One of
on_trial
active
paused
- The subscription's payment collection has been paused. See thepause
attribute below for more information.past_due
- A renewal payment has failed. The subscription will go through 4 payment retries over the course of 2 weeks. If a retry is successful, the subscription's status changes back toactive
. If all four retries are unsuccessful, the status is changed tounpaid
.unpaid
- Payment recovery has been unsuccessful in capturing a payment after 4 attempts. If dunning is enabled in your store, your dunning rules now will determine if the subscription becomesexpired
after a certain period. If dunning is turned off, the status remainsunpaid
(it is up to you to determine what this means for users of your product).cancelled
- The customer or store owner has cancelled future payments, but the subscription is still technically active and valid (on a "grace period"). Theends_at
value shows the date-time when the subscription is scheduled to expire.expired
- The subscription has ended (either it had previously beencancelled
and the grace period created from its final payment has run out, or it was previouslyunpaid
and the subscription was not re-activated during dunning). Theends_at
value shows the date-time when the subscription expired. Customers should no longer have access to your product.
status_formatted
The title-case formatted status of the subscription.
For example, when status
is active
, status_formatted
will be Active
and past_due
will be Past due
.
card_brand
Lowercase brand of the card used to pay for the latest subscription payment. One of
-visa
mastercard
amex
discover
jcb
diners
unionpay
Will be empty for non-card payments.
card_last_four
The last 4 digits of the card used to pay for the latest subscription payment. Will be empty for non-card payments.
pause
An object containing the payment collection pause behaviour options for the subscription, if set. Options include:
mode
- Defines payment pause behaviour, can be one of:void
- If you can't offer your services for a period of time (for maintenance as an example), you can void invoices so your customers aren't charged.free
- Offer your subscription services for free, whilst halting payment collection.
resumes_at
- An ISO 8601 formatted date-time string indicating when the subscription will continue collecting payments.
For a subscription that isn't in the paused
state, the pause object will be null
.
cancelled
A boolean indicating if the subscription has been cancelled.
When cancelled
is true
:
status
will becancelled
ends_at
will be populated with a date-time string
trial_ends_at
If the subscription has a free trial (status
is on_trial
), this will be an ISO 8601 formatted date-time string indicating when the trial period ends. For all other status
values, this will be null
.
billing_anchor
An integer representing a day of the month (21
equals 21st day of the month
). This is the day on which subscription invoice payments are collected.
first_subscription_item
An object representing the first subscription item belonging to this subscription.
id
- The ID of the subscription item.subscription_id
- The ID of the subscription.price_id
- The ID of the pricequantity
- The quantity of the subscription item.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.
Will be null
if there is no subscription item, for example if the subscription is currently in a free trial.
urls
An object of customer-facing URLs for managing the subscription. It contains:
update_payment_method
- A pre-signed URL for managing payment and billing information for the subscription. This can be used in conjunction with Lemon.js to allow your customer to change their billing information from within your application. The URL is valid for 24 hours from time of request.customer_portal
- A pre-signed URL to the Customer Portal, which allows customers to fully manage their subscriptions and billing information from within your application. The URL is valid for 24 hours from time of request.
renews_at
An ISO 8601 formatted date-time string indicating the end of the current billing cycle, and when the next invoice will be issued. This also applies to past_due
subscriptions; renews_at
will reflect the next renewal charge attempt.
ends_at
If the subscription has as status
of cancelled
or expired
, this will be an ISO 8601 formatted date-time string indicating when the subscription expires (or expired). For all other status
values, this will be null
.
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.
test_mode
A boolean indicating if the object was created within test mode.
Subscription object
Update a subscription
For a detailed look at how to manage subscriptions with the API, please read our Developer guide.
Update an existing subscription to specific parameters. With this endpoint, you can:
- Upgrade or downgrade a subscripion to a different Variant.
- Change payment pause collection behaviour
- Update the billing date for when payments are collected
When changing the plan of a subscription, by default we prorate the charge for the next billing cycle. For example, if a customer buys your product on April 1st for $50, they'll be charged $50 immediately. If on April 15th they upgrade to your $100 product, on May 1st they'll be charged $125. This is made up of $100 for renewing, $50 of used time on your upgraded $100 plan from April 15th - May 1st, and then a credited -$25 for unused time on your $50 plan.
Charge | Amount | Running Total |
---|---|---|
Renew Charge | $100 | $100 |
Upgrade plan partially used time | $50 | $150 |
Unused time on previous $50 plan | -$25 | $125 |
If downgrading a subscription, we'll issue a credit which is then applied on the next invoice.
Changing a subscription plan may change the billing date or charge immediately if:
- The variant has a different billing cycle (from monthly to yearly, etc)
- The subscription is no longer free, or is now free
- A trial starts or ends
Attributes
variant_id
The ID of the Variant you want to switch this subscription to. Required if changing a subscription's product/variant.
pause
An object containing the payment collection pause behaviour options for the subscription. Options include:
mode
- Defines payment pause behaviour, can be one of:void
- If you can't offer your services for a period of time (for maintenance as an example), you can void invoices so your customers aren't charged.free
- Offer your subscription services for free, whilst halting payment collection.
resumes_at
(optional) - An ISO 8601 formatted date-time string indicating when the subscription will continue collecting payments.
You can set the pause object to null
to unpause the subscription.
cancelled
Set as true
to cancel the subscription. You can resume a subscription (before the ends_at
date) by setting this to false
.
billing_anchor
- Use an integer representing a day of the month (
21
equals21st day of the month
) to change the day on which subscription invoice payments are collected. - Use
null
or0
to reset the billing anchor to the current date. Doing this will also remove an active trial.
Setting this value to a valid integer (1-31) will set the billing anchor to the next occurrence of that day. For example, if on the 21st of January you set the subscription billing anchor to the 1st, the next occurrence of that day is February 1st. All invoices from that point on will be generated on the 1st of the month.
If the current month doesn’t contain the day that matches your billing_anchor
(for example, if the billing_anchor
is 31 and the month is November), the customer will be charged on the last day of the month.
When setting a new billing anchor day, we calculate the next occurrence and issue a paid, prorated trial which ends on the next occurrence date. When the trial ends, the customer is charged for the full prorated amount.
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.
PATCH /v1/subscriptions/:id
Returns
Returns a subscription object.
Response
Retrieve a subscription
Retrieves the subscription with the given ID.
GET /v1/subscriptions/:id
Returns
Returns a subscription object.
Response
List all subscriptions
Returns a paginated list of subscriptions.
Parameters
store_id
Only return subscriptions belonging to the store with this ID.
order_id
Only return subscriptions belonging to the order with this ID.
order_item_id
Only return subscriptions belonging to the order item with this ID.
product_id
Only return subscriptions belonging to the product with this ID.
variant_id
Only return subscriptions belonging to the variant with this ID.
user_email
Only return subscriptions where the user_email
field is equal to this email address.
status
Only return subscriptions with this status.
GET /v1/subscriptions
Returns
Returns a paginated list of subscription objects ordered by created_at
(descending).
Response
Cancel a Subscription
Cancel an active subscription
DELETE /v1/subscriptions/{id}
Returns
Returns the Subscription object in a cancelled state.