> ## 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. # Update a subscription > Upgrade, downgrade or cancel autorenew for a subscription plan ```py Python theme={null} lotus.update_subscription( customer_id='cust_0569173ee6654369', plan_id="plan_123", replace_plan_id="plan_456", invocing_behavior="add_to_next_invoice", turn_off_auto_renew=True ) lotus.update_subscription( customer_id='cust_0569173ee6654369', plan_id="plan_123", subscription_filters=[{"property_name": "status", "value": "active"}], end_date=datetime.date(2022, 12, 8), ) ``` ```ts Typescript theme={null} await lotus.updateSubscription({ customerId: "cust_234"; planId: "plan_234"; subscriptionFilters: [{property_name: "project_id", value: "3234123"}]; replacePlanId: "plan_235"; invoicingBehavior: "add_to_next_invoice"; usageBehavior: "transfer_to_new_subscription" }); ``` *** ## OpenAPI ````yaml POST /api/subscriptions/update/ 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/update/: post: tags: - api operationId: api_subscriptions_update_create parameters: - in: query name: customer_id schema: type: string nullable: true minLength: 1 description: Filter to a specific customer. required: true - in: query name: plan_id schema: type: string format: uuid description: Filter to a specific plan. required: true - in: query name: subscription_filters schema: type: array items: $ref: '#/components/schemas/SubscriptionFilterRequest' description: >- Filter to a specific set of subscription filters. If your billing model only allows for one subscription per customer, you very likely do not need this field. Must be formatted as a JSON-encoded + stringified list of dictionaries, where each dictionary has a key of 'property_name' and a key of 'value'. requestBody: content: application/json: schema: $ref: >- #/components/schemas/SubscriptionRecordUpdateSerializerOldRequest application/x-www-form-urlencoded: schema: $ref: >- #/components/schemas/SubscriptionRecordUpdateSerializerOldRequest multipart/form-data: schema: $ref: >- #/components/schemas/SubscriptionRecordUpdateSerializerOldRequest responses: '200': content: application/json: schema: type: array items: $ref: '#/components/schemas/SubscriptionRecord' description: '' security: - knoxTokenAuth: [] - OrganizationApiKeyAuth: [] TokenAuth: [] components: schemas: SubscriptionFilterRequest: type: object properties: value: type: string minLength: 1 property_name: type: string minLength: 1 description: 'The string name of the property to filter on. Example: ''product_id''' required: - property_name - value SubscriptionRecordUpdateSerializerOldRequest: type: object properties: replace_plan_id: type: string format: uuid writeOnly: true description: >- [DEPRECATED] Will currently perform a best-effort attempt to find the correct plan version to replace the current plan with. If more than one plan version matches the criteria, this will return an error. Use the change_plan method of a subscription instance instead. 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 turn_off_auto_renew: type: boolean description: Turn off auto renew for the subscription end_date: type: string format: date-time description: Change the end date for the subscription. 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 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 ````