Upgrades and downgrades

curl --request POST \
--url https://api.getlago.com/api/v1/subscriptions \
--header 'Authorization: Bearer <bearer>' \
--data '{
  "subscription": {
      "external_customer_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
      "plan_code": "new_plan",
      "external_id": "existing_sub_id"
    }
  }'

​

Upgrades behavior

An upgrade occurs when the subscription fee of the new plan, calculated on a daily basis, equals or exceeds the subscription fee of the previous plan, regardless of the pricing for usage-based charges.

When a subscription is upgraded:

• Lago promptly applies the new plan to the customer; and
• In the case of a subscription that is paid in advance (at the beginning of the period), Lago issues a credit note for the unused days from the former plan.

​

Downgrades behavior

A downgrade occurs when the subscription fee of the new plan, calculated on a daily basis is lower than the subscription fee of the previous plan, regardless of the pricing for usage-based charges.

When a subscription is downgraded:

• The new plan is applied at the end of the current billing period to ensure that your customer fully benefits from the plan they have already paid for. The newly applied plan will be in a pending state.

​

Webhook messages for upgrades and downgrades

When a subscription is upgraded or downgraded:

• A subscription.terminated webhook message is triggered for the initial plan, with a next_plan_code defined in the payload;
• A subscription.started webhook message is triggered for the new plan, with a previous_plan_code defined in the payload;
• The subscription.external_id is persisted between the two to ensure the continuity of the subscription.