---
title: "POST /api/subscriptions/update/"
method: POST
path: "/api/subscriptions/update/"
tags: ["api"]
---

# POST /api/subscriptions/update/

`POST /api/subscriptions/update/`

## Query parameters

- `customer_id` string, nullable, required
- `plan_id` string, uuid, required
- `subscription_filters` SubscriptionFilterRequest[]
  - `value` string, required
  - `property_name` string, required — The string name of the property to filter on. Example: 'product_id'

## Request body

- SubscriptionRecordUpdateSerializerOldRequest
  - `replace_plan_id` string, uuid — [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` 'add_to_next_invoice' | '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
  - `usage_behavior` 'transfer_to_new_subscription' | 'keep_separate' — 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` boolean — Turn off auto renew for the subscription
  - `end_date` string, date-time — Change the end date for the subscription.

## Response `200`

- SubscriptionRecord[]
  - `subscription_id` string, required
  - `start_date` string, date-time, 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, date-time, 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` SubscriptionFilter[], required
    - `value` string, required
    - `property_name` string, required — The string name of the property to filter on. Example: 'product_id'
  - `customer` LightweightCustomer, required
    - `customer_name` string, nullable, required — The display name of the customer
    - `email` string, email, nullable, required — 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` string, nullable, required — The id provided when creating the customer, we suggest matching with your internal customer id in your backend
  - `billing_plan` LightweightPlanVersion, required
    - `plan_name` string, required
    - `plan_id` string, required
    - `version_id` string, required
    - `version` union, required
      - integer
      - 'custom_version'
  - `fully_billed` boolean, required
  - `addons` LightweightAddOnSubscriptionRecord[], required
    - `addon_subscription_id` string, required
    - `start_date` string, date-time, 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, date-time, required — The time the subscription starts. This will be a string in yyyy-mm-dd HH:mm:ss format in UTC time.
    - `addon` LightweightAddOn, required
      - `addon_name` string, required — The name of the add-on plan.
      - `addon_id` string, required — The ID of the add-on plan.
      - `addon_type` 'flat' | 'usage_based', required
      - `billing_frequency` 'one_time' | 'recurring', required — * `one_time` - one_time * `recurring` - recurring
    - `fully_billed` boolean, required
  - `metadata` object, required

---

[API](https://skmtc.net/uselotus/apis/lotus-api.md) · [All operations](https://skmtc.net/uselotus/apis/lotus-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/uselotus/lotus-api/versions/1f59f4fea13f/schema)