> ## Documentation Index > Fetch the complete documentation index at: https://docs.uselotus.io/llms.txt > Use this file to discover all available pages before exploring further. # Switch a subscription's plan > Upgrade or downgrade the susbcription's plan. 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. ```py Python theme={null} 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' ) ``` ```ts Typescript theme={null} await lotus.switchSubscriptionPlan({ subscription_id: "sub_a623349004cd4947aca1851c64aa6fbd", switch_plan_id: "plan_b5fe8a2603a24c4fa05ffb3fb382fe6d", invoicing_behavior: "add_to_next_invoice", usage_behavior: "transfer_to_new_subscription", // or 'keep_separate' }); ``` *** ## OpenAPI ````yaml POST /api/subscriptions/{subscription_id}/switch_plan/ openapi: 3.0.3 info: title: Lotus API version: 0.9.3 description: >- Lotus is an open-core pricing and billing engine. We enable API companies to automate and optimize their custom usage-based pricing for any metric. servers: [] security: [] paths: /api/subscriptions/{subscription_id}/switch_plan/: post: tags: - api operationId: api_subscriptions_switch_plan_create parameters: - in: path name: subscription_id schema: type: string description: The ID of the subscription which will have its plans switched. required: true requestBody: content: application/json: schema: $ref: '#/components/schemas/SubscriptionRecordSwitchPlanRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/SubscriptionRecordSwitchPlanRequest' multipart/form-data: schema: $ref: '#/components/schemas/SubscriptionRecordSwitchPlanRequest' responses: '200': content: application/json: schema: $ref: '#/components/schemas/SubscriptionRecord' description: '' security: - knoxTokenAuth: [] - OrganizationApiKeyAuth: [] TokenAuth: [] components: schemas: SubscriptionRecordSwitchPlanRequest: type: object properties: switch_plan_id: type: string format: uuid writeOnly: true description: The new plan to switch to. invoicing_behavior: enum: - add_to_next_invoice - invoice_now type: string default: invoice_now description: >- 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 usage_behavior: enum: - transfer_to_new_subscription - keep_separate type: string default: transfer_to_new_subscription description: >- 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 component_fixed_charges_initial_units: type: array items: $ref: '#/components/schemas/ComponentsFixedChargeInitialValueRequest' description: >- 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. SubscriptionRecord: type: object properties: subscription_id: type: string start_date: type: string format: date-time description: >- The time the subscription starts. This will be a string in yyyy-mm-dd HH:mm:ss format in UTC time. end_date: type: string format: date-time description: >- The time the subscription starts. This will be a string in yyyy-mm-dd HH:mm:ss format in UTC time. auto_renew: type: boolean description: Whether the subscription automatically renews. Defaults to true. is_new: type: boolean description: >- Whether this subscription came from a renewal or from a first-time. Defaults to true on creation. subscription_filters: type: array items: $ref: '#/components/schemas/SubscriptionFilter' customer: $ref: '#/components/schemas/LightweightCustomer' billing_plan: $ref: '#/components/schemas/LightweightPlanVersion' fully_billed: type: boolean readOnly: true addons: type: array items: $ref: '#/components/schemas/LightweightAddOnSubscriptionRecord' metadata: type: object additionalProperties: {} required: - addons - auto_renew - billing_plan - customer - end_date - fully_billed - is_new - metadata - start_date - subscription_filters - subscription_id ComponentsFixedChargeInitialValueRequest: type: object properties: metric_id: type: string format: uuid writeOnly: true description: The id of the metric that this initial value is for units: type: number format: double maximum: 10000000000 minimum: 0 exclusiveMaximum: true description: The number of units of the metric that this initial value is for required: - metric_id - units SubscriptionFilter: type: object properties: value: type: string property_name: type: string description: 'The string name of the property to filter on. Example: ''product_id''' required: - property_name - value LightweightCustomer: type: object properties: customer_name: type: string readOnly: true nullable: true description: The display name of the customer email: type: string format: email readOnly: true nullable: true description: >- The primary email address of the customer, must be the same as the email address used to create the customer in the payment provider customer_id: type: string readOnly: true nullable: true description: >- The id provided when creating the customer, we suggest matching with your internal customer id in your backend required: - customer_id - customer_name - email LightweightPlanVersion: type: object properties: plan_name: type: string readOnly: true plan_id: type: string version_id: type: string readOnly: true version: oneOf: - type: integer - enum: - custom_version type: string readOnly: true required: - plan_id - plan_name - version - version_id LightweightAddOnSubscriptionRecord: type: object properties: addon_subscription_id: type: string start_date: type: string format: date-time readOnly: true description: >- The time the subscription starts. This will be a string in yyyy-mm-dd HH:mm:ss format in UTC time. end_date: type: string format: date-time readOnly: true description: >- The time the subscription starts. This will be a string in yyyy-mm-dd HH:mm:ss format in UTC time. addon: $ref: '#/components/schemas/LightweightAddOn' fully_billed: type: boolean readOnly: true required: - addon - addon_subscription_id - end_date - fully_billed - start_date LightweightAddOn: type: object properties: addon_name: type: string description: The name of the add-on plan. addon_id: type: string description: The ID of the add-on plan. addon_type: enum: - flat - usage_based type: string readOnly: true billing_frequency: enum: - one_time - recurring description: |- * `one_time` - one_time * `recurring` - recurring readOnly: true required: - addon_id - addon_name - addon_type - billing_frequency securitySchemes: knoxTokenAuth: type: apiKey in: header name: Authorization description: Token-based authentication with required prefix "Token" OrganizationApiKeyAuth: type: apiKey in: header name: X-API-KEY ````