Switch a subscription's plan
curl --request POST \
--url https://api.uselotus.io/api/subscriptions/{subscription_id}/switch_plan/ \
--header 'Authorization: <authorization>' \
--header 'Content-Type: application/json' \
--data '{
"component_fixed_charges_initial_units": [
{
"metric_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"units": 123
}
],
"invoicing_behavior": "add_to_next_invoice",
"switch_plan_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"usage_behavior": "transfer_to_new_subscription"
}'
{
"addons": [
{
"addon": {
"addon_id": "<string>",
"addon_name": "<string>",
"addon_type": "flat",
"billing_frequency": "one_time"
},
"addon_subscription_id": "<string>",
"end_date": "2023-11-07T05:31:56Z",
"fully_billed": true,
"start_date": "2023-11-07T05:31:56Z"
}
],
"auto_renew": true,
"billing_plan": {
"plan_id": "<string>",
"plan_name": "<string>",
"version": 123,
"version_id": "<string>"
},
"customer": {
"customer_id": "<string>",
"customer_name": "<string>",
"email": "jsmith@example.com"
},
"end_date": "2023-11-07T05:31:56Z",
"fully_billed": true,
"is_new": true,
"metadata": {},
"start_date": "2023-11-07T05:31:56Z",
"subscription_filters": [
{
"property_name": "<string>",
"value": "<string>"
}
],
"subscription_id": "<string>"
}
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
Token-based authentication with required prefix "Token"
Path Parameters
The ID of the subscription which will have its plans switched.
Body
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.
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 Invoiceinvoice_now
- Invoice Now
add_to_next_invoice
, invoice_now
The new plan to switch to.
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 Subscriptionkeep_separate
- Keep Separate
transfer_to_new_subscription
, keep_separate
Response
Whether the subscription automatically renews. Defaults to true.
The time the subscription starts. This will be a string in yyyy-mm-dd HH:mm:ss format in UTC time.
Whether this subscription came from a renewal or from a first-time. Defaults to true on creation.
The time the subscription starts. This will be a string in yyyy-mm-dd HH:mm:ss format in UTC time.
curl --request POST \
--url https://api.uselotus.io/api/subscriptions/{subscription_id}/switch_plan/ \
--header 'Authorization: <authorization>' \
--header 'Content-Type: application/json' \
--data '{
"component_fixed_charges_initial_units": [
{
"metric_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"units": 123
}
],
"invoicing_behavior": "add_to_next_invoice",
"switch_plan_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"usage_behavior": "transfer_to_new_subscription"
}'
{
"addons": [
{
"addon": {
"addon_id": "<string>",
"addon_name": "<string>",
"addon_type": "flat",
"billing_frequency": "one_time"
},
"addon_subscription_id": "<string>",
"end_date": "2023-11-07T05:31:56Z",
"fully_billed": true,
"start_date": "2023-11-07T05:31:56Z"
}
],
"auto_renew": true,
"billing_plan": {
"plan_id": "<string>",
"plan_name": "<string>",
"version": 123,
"version_id": "<string>"
},
"customer": {
"customer_id": "<string>",
"customer_name": "<string>",
"email": "jsmith@example.com"
},
"end_date": "2023-11-07T05:31:56Z",
"fully_billed": true,
"is_new": true,
"metadata": {},
"start_date": "2023-11-07T05:31:56Z",
"subscription_filters": [
{
"property_name": "<string>",
"value": "<string>"
}
],
"subscription_id": "<string>"
}