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 an Order, an Order Item, a Product and a Variant.


The subscription object

Attributes


store_id

The ID of the store 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, cancelled, expired.


status_formatted

The formatted status of the subscription.


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.

The pause object can be null, which indicates payment collection is not paused.


cancelled

A boolean indicating if the subscription has been cancelled.


trial_ends_at

If the subscription has a free trial, this will be an ISO-8601 formatted date-time string indicating when the trial period ends.


billing_anchor

An integer representing a day of the month (21 equals 21st day of the month). This is the day of which subscription invoice payments are collected.


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.

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.


ends_at

If the subscription has been cancelled, this will be an ISO-8601 formatted date-time string indicating when the subscription expires.


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 returned subscription object was created within test mode.

Subscription object

{ "type": "subscriptions", "id": "1", "attributes": { "store_id": 1, "order_id": 1, "order_item_id": 1, "product_id": 1, "variant_id": 1, "product_name": "Example Product", "variant_name": "Example Variant", "user_name": "Darlene Daugherty", "user_email": "[email protected]", "status": "active", "status_formatted": "Active", "pause": null, "cancelled": false, "trial_ends_at": null, "billing_anchor": 12, "urls": { "update_payment_method": "https://app.lemonsqueezy.com/my-orders/2ba92a4e-a00a-45d2-a128-16856ffa8cdf/subscription/8/update-payment-method?expires=1666869343&signature=9985e3bf9007840aeb3951412be475abc17439c449c1af3e56e08e45e1345413" }, "renews_at": "2022-11-12T00:00:00.000000Z", "ends_at": null, "created_at": "2021-08-11T13:47:27.000000Z", "updated_at": "2021-08-11T13:54:19.000000Z", "test_mode": false } }

Update a subscription

Update an existing subscription to specific parameters. With this endpoint, you can:

  • Upgrade & Downgrade a subscripion to a different Product or Variant.
  • Change payment pause collection behaviour
  • Update the billing date for when payments are collected

When changing the plan of a subscription, 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.

ChargeAmountRunning 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


product_id

The ID of the Product Object you want to switch this subscription to. If set, requires a Variant Object ID.


variant_id

The ID of the Variant Object you want to switch this subscription to. Required if product_id set.


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 uncancel (before the ends_at date) by setting to false.


billing_anchor

An integer representing a day of the month (21 equals 21st day of the month). This is the day of which subscription invoice payments are collected.

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.

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.


PATCH /v1/subscriptions/:id

curl -X "PATCH" "https://api.lemonsqueezy.com/v1/subscriptions/1" -H 'Accept: application/vnd.api+json' -H 'Content-Type: application/vnd.api+json' -H 'Authorization: Bearer {api_key}' -d $'{ "data": { "type": "subscriptions", "id": "1", "attributes": { "product_id": 9, "variant_id": 11, "billing_anchor": 29 } } }'

Returns

Returns a subscription object.

Response

{ "type": "subscriptions", "id": "1", "attributes": { "store_id": 1, "order_id": 1, "order_item_id": 1, "product_id": 9, "variant_id": 11, "product_name": "New Plan Product", "variant_name": "New Plan Variant", "user_name": "Darlene Daugherty", "user_email": "[email protected]", "status": "active", "status_formatted": "Active", "pause": null, "cancelled": false, "trial_ends_at": null, "billing_anchor": 29, "urls": { "update_payment_method": "https://app.lemonsqueezy.com/my-orders/2ba92a4e-a00a-45d2-a128-16856ffa8cdf/subscription/8/update-payment-method?expires=1666869343&signature=9985e3bf9007840aeb3951412be475abc17439c449c1af3e56e08e45e1345413" }, "renews_at": "2022-11-12T00:00:00.000000Z", "ends_at": null, "created_at": "2021-08-11T13:47:27.000000Z", "updated_at": "2021-08-11T13:54:19.000000Z", "test_mode": false } }

Retrieve a subscription

Retrieves the subscription with the given ID.

GET /v1/subscriptions/:id

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

Returns

Returns a subscription object.

Response

{ "jsonapi": { "version": "1.0" }, "links": { "self": "https://api.lemonsqueezy.com/v1/subscriptions/1" }, "data": { "type": "subscriptions", "id": "1", "attributes": { "store_id": 1, "order_id": 1, "order_item_id": 1, "product_id": 1, "variant_id": 1, "product_name": "Example Product", "variant_name": "Example Variant", "user_name": "Darlene Daugherty", "user_email": "[email protected]", "status": "active", "status_formatted": "Active", "pause": null, "cancelled": false, "trial_ends_at": null, "billing_anchor": 12, "urls": { "update_payment_method": "https://app.lemonsqueezy.com/my-orders/2ba92a4e-a00a-45d2-a128-16856ffa8cdf/subscription/8/update-payment-method?expires=1666869343&signature=9985e3bf9007840aeb3951412be475abc17439c449c1af3e56e08e45e1345413" }, "renews_at": "2022-11-12T00:00:00.000000Z", "ends_at": null, "created_at": "2021-08-11T13:47:27.000000Z", "updated_at": "2021-08-11T13:54:19.000000Z", "test_mode": false }, "relationships": { "store": { "links": { "related": "https://api.lemonsqueezy.com/v1/subscriptions/1/store", "self": "https://api.lemonsqueezy.com/v1/subscriptions/1/relationships/store" } }, "order": { "links": { "related": "https://api.lemonsqueezy.com/v1/subscriptions/1/order", "self": "https://api.lemonsqueezy.com/v1/subscriptions/1/relationships/order" } }, "order-item": { "links": { "related": "https://api.lemonsqueezy.com/v1/subscriptions/1/order-item", "self": "https://api.lemonsqueezy.com/v1/subscriptions/1/relationships/order-item" } }, "product": { "links": { "related": "https://api.lemonsqueezy.com/v1/subscriptions/1/product", "self": "https://api.lemonsqueezy.com/v1/subscriptions/1/relationships/product" } }, "variant": { "links": { "related": "https://api.lemonsqueezy.com/v1/subscriptions/1/variant", "self": "https://api.lemonsqueezy.com/v1/subscriptions/1/relationships/variant" } } }, "links": { "self": "https://api.lemonsqueezy.com/v1/subscriptions/1" } } }

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.

GET /v1/subscriptions

curl "https://api.lemonsqueezy.com/v1/subscriptions" -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 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/subscriptions?page%5Bnumber%5D=1&page%5Bsize%5D=10&sort=-createdAt", "last": "https://api.lemonsqueezy.com/v1/subscriptions?page%5Bnumber%5D=1&page%5Bsize%5D=10&sort=-createdAt", }, "data": [ { "type": "subscriptions", "id": "1", "attributes": { "store_id": 1, "order_id": 1, "order_item_id": 1, "product_id": 1, "variant_id": 1, "product_name": "Example Product", "variant_name": "Example Variant", "user_name": "Darlene Daugherty", "user_email": "[email protected]", "status": "active", "status_formatted": "Active", "pause": null, "cancelled": false, "trial_ends_at": null, "billing_anchor": 12, "urls": { "update_payment_method": "https://app.lemonsqueezy.com/my-orders/2ba92a4e-a00a-45d2-a128-16856ffa8cdf/subscription/8/update-payment-method?expires=1666869343&signature=9985e3bf9007840aeb3951412be475abc17439c449c1af3e56e08e45e1345413" }, "renews_at": "2022-11-12T00:00:00.000000Z", "ends_at": null, "created_at": "2021-08-11T13:47:27.000000Z", "updated_at": "2021-08-11T13:54:19.000000Z", "test_mode": false }, "relationships": { "store": { "links": { "related": "https://api.lemonsqueezy.com/v1/subscriptions/1/store", "self": "https://api.lemonsqueezy.com/v1/subscriptions/1/relationships/store" } }, "order": { "links": { "related": "https://api.lemonsqueezy.com/v1/subscriptions/1/order", "self": "https://api.lemonsqueezy.com/v1/subscriptions/1/relationships/order" } }, "order-item": { "links": { "related": "https://api.lemonsqueezy.com/v1/subscriptions/1/order-item", "self": "https://api.lemonsqueezy.com/v1/subscriptions/1/relationships/order-item" } }, "product": { "links": { "related": "https://api.lemonsqueezy.com/v1/subscriptions/1/product", "self": "https://api.lemonsqueezy.com/v1/subscriptions/1/relationships/product" } }, "variant": { "links": { "related": "https://api.lemonsqueezy.com/v1/subscriptions/1/variant", "self": "https://api.lemonsqueezy.com/v1/subscriptions/1/relationships/variant" } } }, "links": { "self": "https://api.lemonsqueezy.com/v1/subscriptions/1" } }, {...}, {...}, ] }

Cancel a Subscription

Cancel an active subscription

DELETE /v1/subscriptions/{id}

curl -X "DELETE" "https://api.lemonsqueezy.com/v1/subscriptions/{id}" -H 'Accept: application/vnd.api+json' -H 'Content-Type: application/vnd.api+json' -H 'Authorization: Bearer {api_key}'

Returns

Returns the Subscription Object in a cancelled state.

Response

{ "jsonapi": { "version": "1.0" }, "links": { "self": "https://api.lemonsqueezy.com/v1/subscriptions/1" }, "data": { "type": "subscriptions", "id": "1", "attributes": { "store_id": 1, "order_id": 1, "order_item_id": 1, "product_id": 1, "variant_id": 1, "product_name": "Example Product", "variant_name": "Example Variant", "user_name": "Darlene Daugherty", "user_email": "[email protected]", "status": "cancelled", "status_formatted": "Cancelled", "pause": null, "cancelled": true, "trial_ends_at": null, "billing_anchor": 12, "urls": { "update_payment_method": "https://app.lemonsqueezy.com/my-orders/2ba92a4e-a00a-45d2-a128-16856ffa8cdf/subscription/8/update-payment-method?expires=1666869343&signature=9985e3bf9007840aeb3951412be475abc17439c449c1af3e56e08e45e1345413" }, "renews_at": "2022-11-12T00:00:00.000000Z", "ends_at": "2022-11-12T00:00:00.000000Z", "created_at": "2021-08-11T13:47:27.000000Z", "updated_at": "2021-08-11T13:54:19.000000Z", "test_mode": false }, "relationships": { "store": { "links": { "related": "https://api.lemonsqueezy.com/v1/subscriptions/1/store", "self": "https://api.lemonsqueezy.com/v1/subscriptions/1/relationships/store" } }, "order": { "links": { "related": "https://api.lemonsqueezy.com/v1/subscriptions/1/order", "self": "https://api.lemonsqueezy.com/v1/subscriptions/1/relationships/order" } }, "order-item": { "links": { "related": "https://api.lemonsqueezy.com/v1/subscriptions/1/order-item", "self": "https://api.lemonsqueezy.com/v1/subscriptions/1/relationships/order-item" } }, "product": { "links": { "related": "https://api.lemonsqueezy.com/v1/subscriptions/1/product", "self": "https://api.lemonsqueezy.com/v1/subscriptions/1/relationships/product" } }, "variant": { "links": { "related": "https://api.lemonsqueezy.com/v1/subscriptions/1/variant", "self": "https://api.lemonsqueezy.com/v1/subscriptions/1/relationships/variant" } } }, "links": { "self": "https://api.lemonsqueezy.com/v1/subscriptions/1" } } }