Create a subscription

Add a plan to a customer’s subscription

POST /api/subscriptions/

cURL

cURL

curl --request POST \
  --url https://api.uselotus.io/api/subscriptions/ \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "start_date": "2023-11-07T05:31:56Z",
  "customer_id": "<string>",
  "end_date": "2023-11-07T05:31:56Z",
  "auto_renew": true,
  "is_new": true,
  "subscription_filters": [
    {
      "value": "<string>",
      "property_name": "<string>"
    }
  ],
  "plan_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "component_fixed_charges_initial_units": [
    {
      "metric_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "units": 5000000000
    }
  ],
  "metadata": {}
}
'

201

{
  "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": "[e-mail]",
    "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": {}
}

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.

Python

lotus.create_subscription(
  customer_id='cust_6c237d6c149c47db8f64246b78ecac13',
  plan_id='plan_f17c6153807d4f4b812265a09cf06680',
  start_date='2022-02-23 03:30:00+00:00',
)

Authorizations

knoxTokenAuthOrganizationApiKeyAuth

Authorization · string · header · required

Token-based authentication with required prefix "Token"

Body

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

start_date · string<date-time> · required

The date the subscription starts. This should be a string in YYYY-MM-DD format of the date in UTC time.

customer_id · string | null · required · write-only

The id provided when creating the customer

Minimum string length: 1

end_date · string<date-time>

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.

auto_renew · boolean

Whether the subscription automatically renews. Defaults to true.

is_new · boolean

subscription_filters · object[]

Add filter key, value pairs that define which events will be applied to this plan subscription.

Show child attributes

plan_id · string<uuid> | null · write-only

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.

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.

Show child attributes

metadata · object

A JSON object containing additional information about the subscription.

Show child attributes

Response

201 - 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