POST

/api/subscriptions/{subscription_id}/components/{metric_id}/change_prepaid_units/

X-API-KEY*
curl --request POST \
  --url https://api.uselotus.io/api/subscriptions/{subscription_id}/components/{metric_id}/change_prepaid_units/ \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <x-api-key>' \
  --data '{
  "units": 0
}'
{
  "addons": [
    {
      "addon": {
        "addon_id": "string",
        "addon_name": "string",
        "addon_type": "flat",
        "billing_frequency": "one_time"
      },
      "addon_subscription_id": "string",
      "end_date": "string",
      "fully_billed": "boolean",
      "start_date": "string"
    }
  ],
  "auto_renew": "boolean",
  "billing_plan": {
    "plan_id": "string",
    "plan_name": "string",
    "version_id": "string"
  },
  "customer": {
    "customer_id": "string",
    "customer_name": "string",
    "email": "string"
  },
  "end_date": "string",
  "fully_billed": "boolean",
  "is_new": "boolean",
  "metadata": "object",
  "start_date": "string",
  "subscription_filters": [
    {
      "property_name": "string",
      "value": "string"
    }
  ],
  "subscription_id": "string"
}
lotus.change_prepaid_units(
    subscription_id='sub_a623349004cd4947aca1851c64aa6fbd',
    metric_id='metric_a47ac0bf',
    units=32,
    invoice_now=true
)

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

Authorizationheaderrequired
string

Token-based authentication with required prefix "Token"

​
Path Parameters

metric_idrequired
string

The ID of the metric to alter the prepaid usage for.

subscription_idrequired
string

The ID of the subscription which will have its plans switched.

​
Body

invoice_now
Default: true
boolean

Whether or not to immediately invoice the customer for the change in prepaid units.

unitsrequired
number

The new prepaid units for the customer.

​
Response

addonsrequired
array
auto_renewrequired
boolean

Whether the subscription automatically renews. Defaults to true.

billing_planrequired
object
customerrequired
object
end_daterequired
string

The time the subscription starts. This will be a string in yyyy-mm-dd HH:mm:ss format in UTC time.

fully_billedrequired
boolean
is_newrequired
boolean

Whether this subscription came from a renewal or from a first-time. Defaults to true on creation.

metadatarequired
object
start_daterequired
string

The time the subscription starts. This will be a string in yyyy-mm-dd HH:mm:ss format in UTC time.

subscription_filtersrequired
array
subscription_idrequired
string
Switch a subscription's planAttach an Add-On