POST
/
api
/
subscriptions
/
{subscription_id}
/
switch_plan
/
curl --request POST \
  --url https://api.uselotus.io/api/subscriptions/{subscription_id}/switch_plan/ \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "switch_plan_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "invoicing_behavior": "add_to_next_invoice",
  "usage_behavior": "transfer_to_new_subscription",
  "component_fixed_charges_initial_units": [
    {
      "metric_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "units": 5000000000
    }
  ]
}'
{
  "subscription_id": "<string>",
  "start_date": "2023-11-07T05:31:56Z",
  "end_date": "2023-11-07T05:31:56Z",
  "auto_renew": true,
  "is_new": true,
  "subscription_filters": [
    {
      "value": "<string>",
      "property_name": "<string>"
    }
  ],
  "customer": {
    "customer_name": "<string>",
    "email": "jsmith@example.com",
    "customer_id": "<string>"
  },
  "billing_plan": {
    "plan_name": "<string>",
    "plan_id": "<string>",
    "version_id": "<string>",
    "version": 123
  },
  "fully_billed": true,
  "addons": [
    {
      "addon_subscription_id": "<string>",
      "start_date": "2023-11-07T05:31:56Z",
      "end_date": "2023-11-07T05:31:56Z",
      "addon": {
        "addon_name": "<string>",
        "addon_id": "<string>",
        "addon_type": "flat",
        "billing_frequency": "one_time"
      },
      "fully_billed": true
    }
  ],
  "metadata": {}
}

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
string
headerrequired

Token-based authentication with required prefix "Token"

Path Parameters

subscription_id
string
required

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

Body

switch_plan_id
string

The new plan to switch to.

invoicing_behavior
enum<string>
default: invoice_now

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
usage_behavior
enum<string>
default: transfer_to_new_subscription

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
component_fixed_charges_initial_units
object[]

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.

Response

200 - application/json
subscription_id
string
required
start_date
string
required

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

end_date
string
required

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

auto_renew
boolean
required

Whether the subscription automatically renews. Defaults to true.

is_new
boolean
required

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

subscription_filters
object[]
required
customer
object
required
billing_plan
object
required
fully_billed
boolean
required
addons
object[]
required
metadata
object
required
Update a subscriptionChange Prepaid Units