POST
/
api
/
subscriptions
/
update
/
curl --request POST \
  --url https://api.uselotus.io/api/subscriptions/update/ \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "replace_plan_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "invoicing_behavior": "add_to_next_invoice",
  "usage_behavior": "transfer_to_new_subscription",
  "turn_off_auto_renew": true,
  "end_date": "2023-11-07T05:31:56Z"
}'
[
  {
    "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": {}
  }
]
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),
)

Authorizations

Authorization
string
headerrequired

Token-based authentication with required prefix "Token"

Query Parameters

customer_id
string | null
required

Filter to a specific customer.

plan_id
string
required

Filter to a specific plan.

subscription_filters
object[]

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'.

Body

replace_plan_id
string

[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<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
turn_off_auto_renew
boolean

Turn off auto renew for the subscription

end_date
string

Change the end date for the subscription.

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
Cancel a subscriptionList plans