In Lotus, you can define a certain number of units to be “prepaid” for a subscription. For example, if your business uses seats as a metric, you could define that your plan has 5 seats “prepaid” for each subscription. This means that the subscription will have 5 seats available for use, and you can add more seats as needed.
This feature lets you have the benefits or charging flat fees in advance, while still metering the usage of the metric and allowing you to add more units as needed.
This API is not currently available in our SDKs, but please contact us if you would like to use it as part of your workflow.
If the change decreases the number of prepaid units, then the difference is awarded to the customer as a credit. If it icnreases, then you can choose between invoicing the difference immediately or adding it to the next invoice.
Authorizations
Authorization
string
headerrequired
Token-based authentication with required prefix "Token"
Path Parameters
metric_id
string
required
The ID of the metric to alter the prepaid usage for.
subscription_id
string
required
The ID of the subscription which will have its plans switched.
Body
invoice_now
boolean
default: true
Whether or not to immediately invoice the customer for the change in prepaid units.
units
number
required
The new prepaid units for the customer.
Response
200 - application/json
addons
object[]
required
addons.addon
object
required
addons.addon.addon_id
string
required
The ID of the add-on plan.
addons.addon.addon_name
string
required
The name of the add-on plan.
addons.addon.addon_type
enum<string>
required
Available options:
flat,
usage_based
addons.addon.billing_frequency
enum<string>
required
one_time - one_time
recurring - recurring
Available options:
one_time,
recurring
addons.addon_subscription_id
string
required
addons.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.
addons.fully_billed
boolean
required
addons.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.
auto_renew
boolean
required
Whether the subscription automatically renews. Defaults to true.
billing_plan
object
required
billing_plan.plan_id
string
required
billing_plan.plan_name
string
required
billing_plan.version
required
billing_plan.version_id
string
required
customer
object
required
customer.customer_id
string | null
required
The id provided when creating the customer, we suggest matching with your internal customer id in your backend
customer.customer_name
string | null
required
The display name of the customer
customer.email
string | null
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
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.
fully_billed
boolean
required
is_new
boolean
required
Whether this subscription came from a renewal or from a first-time. Defaults to true on creation.
metadata
object
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.
subscription_filters
object[]
required
subscription_filters.property_name
string
required
The string name of the property to filter on. Example: 'product_id'