GET
/
api
/
plans
/
curl --request GET \
  --url https://api.uselotus.io/api/plans/ \
  --header 'Authorization: <api-key>'
[
  {
    "active_subscriptions": 123,
    "active_version": 123,
    "display_version": {
      "active_from": "2023-11-07T05:31:56Z",
      "active_to": "2023-11-07T05:31:56Z",
      "components": [
        {
          "billable_metric": {
            "aggregation_type": "<string>",
            "categorical_filters": [
              {
                "comparison_value": [
                  "<string>"
                ],
                "operator": "isin",
                "property_name": "<string>"
              }
            ],
            "custom_sql": "<string>",
            "event_name": "<string>",
            "event_type": "delta",
            "granularity": "seconds",
            "is_cost_metric": true,
            "metric_id": "<string>",
            "metric_name": "<string>",
            "metric_type": "counter",
            "numeric_filters": [
              {
                "comparison_value": 123,
                "operator": "gte",
                "property_name": "<string>"
              }
            ],
            "property_name": "<string>",
            "proration": "seconds"
          },
          "invoicing_interval_count": 123,
          "invoicing_interval_unit": "day",
          "prepaid_charge": {
            "charge_behavior": "prorate",
            "units": 123
          },
          "pricing_unit": {
            "code": "<string>",
            "name": "<string>",
            "symbol": "<string>"
          },
          "reset_interval_count": 123,
          "reset_interval_unit": "day",
          "tiers": [
            {
              "batch_rounding_type": "<any>",
              "cost_per_batch": 123,
              "metric_units_per_batch": 123,
              "range_end": 123,
              "range_start": 123,
              "type": "flat"
            }
          ]
        }
      ],
      "created_on": "2023-11-07T05:31:56Z",
      "currency": {
        "code": "<string>",
        "name": "<string>",
        "symbol": "<string>"
      },
      "description": "<string>",
      "features": [
        {
          "feature_description": "<string>",
          "feature_id": "<string>",
          "feature_name": "<string>"
        }
      ],
      "flat_fee_billing_type": "in_advance",
      "flat_rate": 123,
      "localized_name": "<string>",
      "plan_name": "<string>",
      "price_adjustment": {
        "price_adjustment_amount": 123,
        "price_adjustment_description": "<string>",
        "price_adjustment_name": "<string>",
        "price_adjustment_type": "percentage"
      },
      "recurring_charges": [
        {
          "amount": 123,
          "charge_behavior": "prorate",
          "charge_timing": "in_advance",
          "invoicing_interval_count": 123,
          "invoicing_interval_unit": "day",
          "name": "<string>",
          "pricing_unit": {
            "code": "<string>",
            "name": "<string>",
            "symbol": "<string>"
          },
          "reset_interval_count": 123,
          "reset_interval_unit": "day"
        }
      ],
      "status": "active",
      "target_customers": [
        {
          "customer_id": "<string>",
          "customer_name": "<string>",
          "email": "jsmith@example.com"
        }
      ],
      "usage_billing_frequency": "<string>",
      "version": 123
    },
    "external_links": [
      {
        "external_plan_id": "<string>",
        "source": "stripe"
      }
    ],
    "num_versions": 123,
    "parent_plan": {
      "plan_id": "<string>",
      "plan_name": "<string>"
    },
    "plan_description": "<string>",
    "plan_duration": "monthly",
    "plan_id": "<string>",
    "plan_name": "<string>",
    "status": "<string>",
    "tags": [
      "<string>"
    ],
    "target_customer": {
      "customer_id": "<string>",
      "customer_name": "<string>",
      "email": "jsmith@example.com"
    },
    "versions": [
      {
        "active_from": "2023-11-07T05:31:56Z",
        "active_to": "2023-11-07T05:31:56Z",
        "components": [
          {
            "billable_metric": {
              "aggregation_type": "<string>",
              "categorical_filters": [
                {
                  "comparison_value": [
                    "<string>"
                  ],
                  "operator": "isin",
                  "property_name": "<string>"
                }
              ],
              "custom_sql": "<string>",
              "event_name": "<string>",
              "event_type": "delta",
              "granularity": "seconds",
              "is_cost_metric": true,
              "metric_id": "<string>",
              "metric_name": "<string>",
              "metric_type": "counter",
              "numeric_filters": [
                {
                  "comparison_value": 123,
                  "operator": "gte",
                  "property_name": "<string>"
                }
              ],
              "property_name": "<string>",
              "proration": "seconds"
            },
            "invoicing_interval_count": 123,
            "invoicing_interval_unit": "day",
            "prepaid_charge": {
              "charge_behavior": "prorate",
              "units": 123
            },
            "pricing_unit": {
              "code": "<string>",
              "name": "<string>",
              "symbol": "<string>"
            },
            "reset_interval_count": 123,
            "reset_interval_unit": "day",
            "tiers": [
              {
                "batch_rounding_type": "<any>",
                "cost_per_batch": 123,
                "metric_units_per_batch": 123,
                "range_end": 123,
                "range_start": 123,
                "type": "flat"
              }
            ]
          }
        ],
        "created_on": "2023-11-07T05:31:56Z",
        "currency": {
          "code": "<string>",
          "name": "<string>",
          "symbol": "<string>"
        },
        "description": "<string>",
        "features": [
          {
            "feature_description": "<string>",
            "feature_id": "<string>",
            "feature_name": "<string>"
          }
        ],
        "flat_fee_billing_type": "in_advance",
        "flat_rate": 123,
        "localized_name": "<string>",
        "plan_name": "<string>",
        "price_adjustment": {
          "price_adjustment_amount": 123,
          "price_adjustment_description": "<string>",
          "price_adjustment_name": "<string>",
          "price_adjustment_type": "percentage"
        },
        "recurring_charges": [
          {
            "amount": 123,
            "charge_behavior": "prorate",
            "charge_timing": "in_advance",
            "invoicing_interval_count": 123,
            "invoicing_interval_unit": "day",
            "name": "<string>",
            "pricing_unit": {
              "code": "<string>",
              "name": "<string>",
              "symbol": "<string>"
            },
            "reset_interval_count": 123,
            "reset_interval_unit": "day"
          }
        ],
        "status": "active",
        "target_customers": [
          {
            "customer_id": "<string>",
            "customer_name": "<string>",
            "email": "jsmith@example.com"
          }
        ],
        "usage_billing_frequency": "<string>",
        "version": 123
      }
    ]
  }
]

Retrieves an array of plan objects.

Out of the parameters below, duration, exclude_tags, include_tags, and include_tags_all will filter plan objects. version_currency_code, version_custom_type, and version_status will filter versions within those plans. If a plan has no versions that match the filter, it will not be returned.

lotus.list_plans()

Authorizations

Authorization
string
headerrequired

Token-based authentication with required prefix "Token"

Query Parameters

duration
enum<string>

Filter to plans that have this duration.

  • monthly - Monthly
  • quarterly - Quarterly
  • yearly - Yearly
Available options:
monthly,
quarterly,
yearly
exclude_tags
string[]

Filter to plans that do not have any of the tags in this list.

include_tags
string[]

Filter to plans that have any of the tags in this list.

include_tags_all
string[]

Filter to plans that have all of the tags in this list.

version_currency_code
string

Filter to versions that have the currency specified by this currency code.

version_custom_type
enum<string>
default: all

Filter to versions that have this custom type. If you choose custom_only, you will only see versions that have target customers. If you choose public_only, you will only see versions that do not have target customers.

  • custom_only - Custom Only
  • public_only - Public Only
  • all - All
Available options:
custom_only,
public_only,
all
version_status
enum<string>[]

Filter to versions that have this status. Ended means it has an active_to date in the past. Not started means it has an active_from date in the future or null.

Available options:
active,
ended,
not_started

Response

200 - application/json
active_subscriptions
integer
required

The number of active subscriptions that this plan has across all versions.

active_version
integer
required

This plan's currently active version.

display_version
object
required

[DEPRECATED] Display version has been deprecated. Use 'versions' instead. We will still return this field for now with some heuristics for figuring out what the desired version is, but it will be removed in the near future.

external_links
object[]
required

The external links that this plan has.

num_versions
integer
required

The number of versions that this plan has.

parent_plan
object
required

[DEPRECATED] The parent plan that this plan has.

plan_description
string | null
required

Description of the plan

plan_duration
enum<string> | null
required

Duration of the plan

  • monthly - Monthly
  • quarterly - Quarterly
  • yearly - Yearly
Available options:
monthly,
quarterly,
yearly,
plan_id
string
required
plan_name
string
required

Name of the plan

status
string
required

[DEPRECATED] The status of this plan.

tags
string[]
required

The tags that this plan has.

target_customer
object
required

[DEPRECATED] The target customer that this plan has.

versions
object[]
required

This plan's versions.