Update a Subscription

PATCH

/v1/subscriptions/:id

Updates the subscription with the given ID and provided attributes.

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.

Note about PayPal payment

For all subscriptions that have PayPal as their payment system, the update endpoint will not modify the subscription. Instead the subscription object will have a value present in the urls.customer_portal_update_subscription key. You can use this value to redirect your customer to the Customer Portal to allow a succesful subscription modification.

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.

trial_ends_at

An ISO 8601 formatted date-time string indicating when the subscription’s free trial should end.

billing_anchor

Use an integer representing a day of the month (21 equals 21st day of the month) to change the day on which subscription invoice payments are collected.
Use null or 0 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.

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

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": {
      "variant_id": 11,
      "billing_anchor": 29,
      "trial_ends_at": "2024-04-20T10:30:00Z"
    }
  }
}'

Returns

Returns the updated Subscription object.

{
  "type": "subscriptions",
  "id": "1",
  "attributes": {
    "store_id": 1,
    "customer_id": 1,
    "order_id": 1,
    "order_item_id": 1,
    "product_id": 9,
    "variant_id": 11,
    "product_name": "Lemonady",
    "variant_name": "Citrus Blast",
    "user_name": "John Doe",
    "user_email": "[email protected]",
    "status": "active",
    "status_formatted": "Active",
    "pause": null,
    "cancelled": false,
    "trial_ends_at": null,
    "billing_anchor": 29,
    "first_subscription_item": {
      "id": 1,
      "subscription_id": 1,
      "price_id": 1,
      "quantity": 5,
      "created_at": "2021-08-11T13:47:28.000000Z",
      "updated_at": "2021-08-11T13:47:28.000000Z"
    },
    "urls": {
      "update_payment_method": "https://my-store.lemonsqueezy.com/subscription/1/payment-details?expires=1666869343&signature=9985e3bf9007840aeb3951412be475abc17439c449c1af3e56e08e45e1345413",
      "customer_portal": "https://my-store.lemonsqueezy.com/billing?expires=1666869343&signature=82ae290ceac8edd4190c82825dd73a8743346d894a8ddbc4898b97eb96d105a5"
    },
    "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
  }
}

← The subscription object

Retrieve a subscription →

Was this page helpful?