Token-based authentication with required prefix "Token"
object
*
auto_renew
boolean
auto_renew
boolean
Whether the subscription automatically renews. Defaults to true.
component_fixed_charges_initial_units
array
component_fixed_charges_initial_units
array
The initial units for the plan components' prepaid fixed charges. This is only required if the plan has plan components where you did not specify the initial units.
customer_id
string
*
customer_id
Required
string
The id provided when creating the customer
end_date
string
end_date
string
The date the subscription ends. This should be a string in YYYY-MM-DD format of the date in UTC time. If you don’t set it (recommended), we will use the information in the billing plan to automatically calculate this.
is_new
boolean
is_new
boolean
metadata
object
metadata
object
A JSON object containing additional information about the subscription.
plan_id
string
plan_id
string
The Lotus plan_id, found in the billing plan object. We will make a best-effort attempt to find the correct plan version (matching preferred currencies, prioritizing custom plans), but if more than one plan version or no plan version matches these criteria this will return an error.
start_date
string
*
start_date
Required
string
The date the subscription starts. This should be a string in YYYY-MM-DD format of the date in UTC time.
subscription_filters
array
subscription_filters
array
Add filter key, value pairs that define which events will be applied to this plan subscription.
A subscription associates one of your customers with one of your billing plans. You can safely give a customer multiple subscriptions to different plans.
If you want to give a single customer multiple subscriptions to the same plan (for example, one for each of their environments), you can do that using subscription_filters. For more details on how to use them and what they do, see the subscription filters documentation.
If any of your usage components has a prepaid charge associated with it, you can specify how many units they prepaid for as part of this call. If you don’t specify a value, the component’s default value will be used. If there was no default value, the susbcription creation will fail.
Token-based authentication with required prefix "Token"
Body
auto_renew
boolean
Whether the subscription automatically renews. Defaults to true.
component_fixed_charges_initial_units
object[]
The initial units for the plan components' prepaid fixed charges. This is only required if the plan has plan components where you did not specify the initial units.
component_fixed_charges_initial_units.metric_id
string
required
The id of the metric that this initial value is for
component_fixed_charges_initial_units.units
number
required
The number of units of the metric that this initial value is for
customer_id
string | null
required
The id provided when creating the customer
end_date
string
The date the subscription ends. This should be a string in YYYY-MM-DD format of the date in UTC time. If you don’t set it (recommended), we will use the information in the billing plan to automatically calculate this.
is_new
boolean
metadata
object
A JSON object containing additional information about the subscription.
plan_id
string | null
The Lotus plan_id, found in the billing plan object. We will make a best-effort attempt to find the correct plan version (matching preferred currencies, prioritizing custom plans), but if more than one plan version or no plan version matches these criteria this will return an error.
start_date
string
required
The date the subscription starts. This should be a string in YYYY-MM-DD format of the date in UTC time.
subscription_filters
object[]
Add filter key, value pairs that define which events will be applied to this plan subscription.
subscription_filters.property_name
string
required
The string name of the property to filter on. Example: 'product_id'
subscription_filters.value
string
required
Response
201 - 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'