Change Prepaid Units

cURL

curl --request POST \
  --url https://api.uselotus.io/api/subscriptions/{subscription_id}/components/{metric_id}/change_prepaid_units/ \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "units": 0,
  "invoice_now": true
}
'

import requests

url = "https://api.uselotus.io/api/subscriptions/{subscription_id}/components/{metric_id}/change_prepaid_units/"

payload = {
    "units": 0,
    "invoice_now": True
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({units: 0, invoice_now: true})
};

fetch('https://api.uselotus.io/api/subscriptions/{subscription_id}/components/{metric_id}/change_prepaid_units/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.uselotus.io/api/subscriptions/{subscription_id}/components/{metric_id}/change_prepaid_units/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'units' => 0,
    'invoice_now' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.uselotus.io/api/subscriptions/{subscription_id}/components/{metric_id}/change_prepaid_units/"

	payload := strings.NewReader("{\n  \"units\": 0,\n  \"invoice_now\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.uselotus.io/api/subscriptions/{subscription_id}/components/{metric_id}/change_prepaid_units/")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"units\": 0,\n  \"invoice_now\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.uselotus.io/api/subscriptions/{subscription_id}/components/{metric_id}/change_prepaid_units/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"units\": 0,\n  \"invoice_now\": true\n}"

response = http.request(request)
puts response.read_body

{
  "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": {}
}

POST

api

subscriptions

{subscription_id}

components

{metric_id}

change_prepaid_units

cURL

curl --request POST \
  --url https://api.uselotus.io/api/subscriptions/{subscription_id}/components/{metric_id}/change_prepaid_units/ \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "units": 0,
  "invoice_now": true
}
'

import requests

url = "https://api.uselotus.io/api/subscriptions/{subscription_id}/components/{metric_id}/change_prepaid_units/"

payload = {
    "units": 0,
    "invoice_now": True
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({units: 0, invoice_now: true})
};

fetch('https://api.uselotus.io/api/subscriptions/{subscription_id}/components/{metric_id}/change_prepaid_units/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.uselotus.io/api/subscriptions/{subscription_id}/components/{metric_id}/change_prepaid_units/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'units' => 0,
    'invoice_now' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.uselotus.io/api/subscriptions/{subscription_id}/components/{metric_id}/change_prepaid_units/"

	payload := strings.NewReader("{\n  \"units\": 0,\n  \"invoice_now\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.uselotus.io/api/subscriptions/{subscription_id}/components/{metric_id}/change_prepaid_units/")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"units\": 0,\n  \"invoice_now\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.uselotus.io/api/subscriptions/{subscription_id}/components/{metric_id}/change_prepaid_units/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"units\": 0,\n  \"invoice_now\": true\n}"

response = http.request(request)
puts response.read_body

{
  "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.change_prepaid_units(
    subscription_id='sub_a623349004cd4947aca1851c64aa6fbd',
    metric_id='metric_a47ac0bf',
    units=32,
    invoice_now=true
)

await lotus.changePrepaidUnits({
  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

Authorization

string

header

required

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

units

number<double>

required

The new prepaid units for the customer.

Required range: -10000000000 < x < 10000000000

invoice_now

boolean

default:true

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

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

Show child attributes

customer

object

required

Show child attributes

billing_plan

object

required

Show child attributes

fully_billed

boolean

required

read-only

addons

object[]

required

Show child attributes

metadata

object

required

Show child attributes