Skip to main content
POST
/
api
/
subscriptions
/
cancel
/
cURL
curl --request POST \
  --url https://api.uselotus.io/api/subscriptions/cancel/ \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "flat_fee_behavior": "refund",
  "usage_behavior": "bill_full",
  "invoicing_behavior": "invoice_now"
}'
[
  {
    "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.cancel_subscription(
    customer_id='cust_0569173ee6654369',
    subscription_filters=[
        {
            "property_name": "status",
            "value": "active",
        },
    ],
    flat_fee_behavior='charge_prorated',
    bill_usage=True,
    invoicing_behavior='add_to_next_invoice',
)

lotus.cancel_subscription(
    plan_id='plan_A',
    subscription_filters=[
        {
            "property_name": "created_date",
            "value": "2020-08-15",
        },
    ],
    flat_fee_behavior='charge_full',
    bill_usage=False,
    invoicing_behavior='invoice_now',
)

Authorizations

​
Authorization
string
header
required

Token-based authentication with required prefix "Token"

Query Parameters

​
customer_id
string | null
required

Filter to a specific customer.

Minimum length: 1
​
plan_id
string<uuid>

Filter to a specific plan. If not specified, all plans will be included in the cancellation request.

​
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

​
flat_fee_behavior
enum<string> | null

When canceling a subscription, the behavior used to calculate the flat fee. If null or not provided, the charge's default behavior will be used according to the subscription's start and end dates. If charge_full, the full flat fee will be charged, regardless of the duration of the subscription. If refund, the flat fee will not be charged. If charge_prorated, the prorated flat fee will be charged.

  • refund - Refund
  • charge_prorated - Prorate
  • charge_full - Charge Full
Available options:
refund,
charge_prorated,
charge_full
​
usage_behavior
enum<string>
default:bill_full

If bill_full, current usage will be billed on the invoice. If bill_none, current unbilled usage will be dropped from the invoice. Defaults to bill_full.

  • bill_full - Bill Full
  • bill_none - Bill None
Available options:
bill_full,
bill_none
​
invoicing_behavior
enum<string>
default:invoice_now

Whether to invoice now or invoice at the end of the billing period. Defaults to invoice now.

  • add_to_next_invoice - Add to Next Invoice
  • invoice_now - Invoice Now
Available options:
add_to_next_invoice,
invoice_now

Response

200 - application/json
​
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
object[]
required
​
customer
object
required
​
billing_plan
object
required
​
fully_billed
boolean
required
​
addons
object[]
required
​
metadata
object
required