Lotus home pagelight logo
Subscriptions
Switch a subscription's plan
POST

/api/subscriptions/{subscription_id}/switch_plan/

X-API-KEY*
Authorization*
curl --request POST \
  --url https://api.uselotus.io/api/subscriptions/{subscription_id}/switch_plan/ \
  --header 'Authorization: <authorization>' \
  --header 'X-API-KEY: <x-api-key>'

Keep in mind that Lotus internally updates the subscription ID when you upgrade or downgrade a subscription. This means that the old ID will no longer be valid.

lotus.switch_subscription_plan(
  subscription_id='sub_a623349004cd4947aca1851c64aa6fbd',
  switch_plan_id='plan_b5fe8a2603a24c4fa05ffb3fb382fe6d',
  invoicing_behavior='add_to_next_invoice',
  usage_behavior='transfer_to_new_subscription', # or 'keep_separate'
)

​
Authorizations

Authorization[header]required
string

Token-based authentication with required prefix "Token"

​
Path Parameters

subscription_idrequired
string

The ID of the subscription which will have its plans switched.

​
Body

component_fixed_charges_initial_units
array

The initial units for the plan components' prepaid fixed charges. In the context of swithciong plans, this is only required if the new plan has a component the old plan did not have, that has a prepaid charge, that deos not have a default.

invoicing_behaviorDefault: "invoice_now"
string

The invoicing behavior to use when replacing the plan. Invoice now will invoice the customer for the prorated difference of the old plan and the new plan, whereas add_to_next_invoice will wait until the end of the subscription to do the calculation.

  • add_to_next_invoice - Add to Next Invoice
  • invoice_now - Invoice Now
Available options:
add_to_next_invoice,
invoice_now
switch_plan_id
string

The new plan to switch to.

usage_behaviorDefault: "transfer_to_new_subscription"
string

The usage behavior to use when replacing the plan. Transfer to new subscription will transfer the usage from the old subscription to the new subscription, whereas keep_separate will reset the usage to 0 for the new subscription, while keeping the old usage on the old subscription and charging for that appropriately at the end of the month.

  • transfer_to_new_subscription - Transfer to New Subscription
  • keep_separate - Keep Separate
Available options:
transfer_to_new_subscription,
keep_separate

​
Response

addonsrequired
array
auto_renewrequired
boolean

Whether the subscription automatically renews. Defaults to true.

billing_planrequired
object
customerrequired
object
end_daterequired
string

The time the subscription starts. This will be a string in yyyy-mm-dd HH:mm:ss format in UTC time.

fully_billedrequired
boolean
is_newrequired
boolean

Whether this subscription came from a renewal or from a first-time. Defaults to true on creation.

metadatarequired
object
start_daterequired
string

The time the subscription starts. This will be a string in yyyy-mm-dd HH:mm:ss format in UTC time.

subscription_filtersrequired
array
subscription_idrequired
string