---
title: "GET /api/plans/"
method: GET
path: "/api/plans/"
tags: ["api"]
---

# GET /api/plans/

`GET /api/plans/`

## Query parameters

- `duration` 'monthly' | 'quarterly' | 'yearly'
- `exclude_tags` string[]
- `include_tags` string[]
- `include_tags_all` string[]
- `version_currency_code` string
- `version_custom_type` 'custom_only' | 'public_only' | 'all'
- `version_status` string[]

## Response `200`

- Plan[]
  - `plan_id` string, required
  - `plan_name` string, required — Name of the plan
  - `plan_duration` 'monthly' | 'quarterly' | 'yearly' | 'null', nullable, required — Duration of the plan * `monthly` - Monthly * `quarterly` - Quarterly * `yearly` - Yearly
  - `plan_description` string, nullable, required — Description of the plan
  - `external_links` InitialExternalPlanLink[], required — The external links that this plan has.
    - `source` 'stripe' | 'braintree', required — * `stripe` - Stripe * `braintree` - Braintree
    - `external_plan_id` string, required
  - `num_versions` integer, required — The number of versions that this plan has.
  - `active_version` integer, required — This plan's currently active version.
  - `active_subscriptions` integer, required — The number of active subscriptions that this plan has across all versions.
  - `tags` string[], required — The tags that this plan has.
  - `versions` PlanVersion[], required — This plan's versions.
    - `recurring_charges` RecurringCharge[], required
      - `name` string, required
      - `charge_timing` 'in_advance' | 'in_arrears', required — * `in_advance` - in_advance * `in_arrears` - in_arrears
      - `charge_behavior` 'prorate' | 'full', required — * `prorate` - prorate * `full` - full
      - `amount` number, double, required
      - `pricing_unit` PricingUnit, required
        - `code` string, required
        - `name` string, required
        - `symbol` string, required
      - `invoicing_interval_unit` 'day' | 'week' | 'month' | 'year' | 'null', nullable, required — * `day` - day * `week` - week * `month` - month * `year` - year
      - `invoicing_interval_count` integer, nullable, required
      - `reset_interval_unit` 'day' | 'week' | 'month' | 'year' | 'null', nullable, required — * `day` - day * `week` - week * `month` - month * `year` - year
      - `reset_interval_count` integer, nullable, required
    - `components` PlanComponent[], required
      - `billable_metric` Metric, required
        - `metric_id` string, required
        - `event_name` string, required — Name of the event that this metric is tracking.
        - `property_name` string, nullable, required — The name of the property of the event that should be used for this metric. Doesn't apply if the metric is of type 'counter' with an aggregation of count.
        - `aggregation_type` string, required
        - `granularity` 'seconds' | 'minutes' | 'hours' | 'days' | 'months' | 'quarters' | 'years' | 'total' | 'null', nullable, required — The granularity of the metric. Only applies to metrics of type 'gauge' or 'rate'. * `seconds` - Second * `minutes` - Minute * `hours` - Hour * `days` - Day * `months` - Month * `quarters` - Quarter * `years` - Year * `total` - Total
        - `event_type` 'delta' | 'total' | 'null', nullable, required — Used only for metrics of type 'gauge'. Please refer to our documentation for an explanation of the different types. * `delta` - Delta * `total` - Total
        - `metric_type` 'counter' | 'rate' | 'custom' | 'gauge', required — The type of metric that this is. Please refer to our documentation for an explanation of the different types. * `counter` - Counter * `rate` - Rate * `custom` - Custom * `gauge` - Gauge
        - `metric_name` string, required
        - `numeric_filters` NumericFilter[], required
          - `property_name` string, required
          - `operator` 'gte' | 'gt' | 'eq' | 'lt' | 'lte', required — * `gte` - Greater than or equal to * `gt` - Greater than * `eq` - Equal to * `lt` - Less than * `lte` - Less than or equal to
          - `comparison_value` number, double, required
        - `categorical_filters` CategoricalFilter[], required
          - `property_name` string, required
          - `operator` 'isin' | 'isnotin', required — * `isin` - Is in * `isnotin` - Is not in
          - `comparison_value` string[], required
        - `is_cost_metric` boolean, required — Whether or not this metric is a cost metric (used to track costs to your business).
        - `custom_sql` string, nullable, required — A custom SQL query that can be used to define the metric. Please refer to our documentation for more information.
        - `proration` 'seconds' | 'minutes' | 'hours' | 'days' | 'months' | 'quarters' | 'years' | 'total' | 'null', nullable, required — The proration of the metric. Only applies to metrics of type 'gauge'. * `seconds` - Second * `minutes` - Minute * `hours` - Hour * `days` - Day * `months` - Month * `quarters` - Quarter * `years` - Year * `total` - Total
      - `tiers` PriceTier[], required
        - `type` 'flat' | 'per_unit' | 'free', required — * `flat` - flat * `per_unit` - per_unit * `free` - free
        - `range_start` number, double, required
        - `range_end` number, double, nullable, required
        - `cost_per_batch` number, double, nullable, required
        - `metric_units_per_batch` number, double, nullable, required
        - `batch_rounding_type` unknown, required
      - `pricing_unit` PricingUnit, required
        - `code` string, required
        - `name` string, required
        - `symbol` string, required
      - `invoicing_interval_unit` 'day' | 'week' | 'month' | 'year' | 'null', nullable, required — * `day` - day * `week` - week * `month` - month * `year` - year
      - `invoicing_interval_count` integer, nullable, required
      - `reset_interval_unit` 'day' | 'week' | 'month' | 'year' | 'null', nullable, required — * `day` - day * `week` - week * `month` - month * `year` - year
      - `reset_interval_count` integer, nullable, required
      - `prepaid_charge` ComponentCharge, required
        - `units` number, double, nullable, required — The number of units to charge for. If left null, then it will be required at subscription create time.
        - `charge_behavior` 'prorate' | 'full', required — * `prorate` - prorate * `full` - full
    - `features` Feature[], required
      - `feature_id` string, required
      - `feature_name` string, required
      - `feature_description` string, nullable, required
    - `price_adjustment` PriceAdjustment, required
      - `price_adjustment_name` string, required
      - `price_adjustment_description` string, nullable, required
      - `price_adjustment_type` 'percentage' | 'fixed' | 'price_override', required — * `percentage` - Percentage * `fixed` - Fixed * `price_override` - Price Override
      - `price_adjustment_amount` number, double, required
    - `version` union, required
      - integer
      - 'custom_version'
    - `status` 'active' | 'retiring' | 'grandfathered' | 'deleted' | 'inactive' | 'not_started', required — * `active` - Active * `retiring` - Retiring * `grandfathered` - Grandfathered * `deleted` - Deleted * `inactive` - Inactive * `not_started` - Not Started
    - `plan_name` string, required
    - `currency` PricingUnit, required
      - `code` string, required
      - `name` string, required
      - `symbol` string, required
    - `active_from` string, date-time, nullable, required
    - `active_to` string, date-time, nullable, required
    - `localized_name` string, nullable, required
    - `target_customers` LightweightCustomer[], required
      - `customer_name` string, nullable, required — The display name of the customer
      - `email` string, email, nullable, 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
      - `customer_id` string, nullable, required — The id provided when creating the customer, we suggest matching with your internal customer id in your backend
    - `created_on` string, date-time, required
    - `usage_billing_frequency` string, nullable, required
    - `flat_fee_billing_type` 'in_advance' | 'in_arrears', required — * `in_advance` - in_advance * `in_arrears` - in_arrears
    - `flat_rate` number, double, required
    - `description` string, nullable, required
  - `parent_plan` PlanNameAndID, required
    - `plan_name` string, required — Name of the plan
    - `plan_id` string, required
  - `target_customer` LightweightCustomer, required
    - `customer_name` string, nullable, required — The display name of the customer
    - `email` string, email, nullable, 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
    - `customer_id` string, nullable, required — The id provided when creating the customer, we suggest matching with your internal customer id in your backend
  - `display_version` PlanVersion, required
    - `recurring_charges` RecurringCharge[], required
      - `name` string, required
      - `charge_timing` 'in_advance' | 'in_arrears', required — * `in_advance` - in_advance * `in_arrears` - in_arrears
      - `charge_behavior` 'prorate' | 'full', required — * `prorate` - prorate * `full` - full
      - `amount` number, double, required
      - `pricing_unit` PricingUnit, required
        - `code` string, required
        - `name` string, required
        - `symbol` string, required
      - `invoicing_interval_unit` 'day' | 'week' | 'month' | 'year' | 'null', nullable, required — * `day` - day * `week` - week * `month` - month * `year` - year
      - `invoicing_interval_count` integer, nullable, required
      - `reset_interval_unit` 'day' | 'week' | 'month' | 'year' | 'null', nullable, required — * `day` - day * `week` - week * `month` - month * `year` - year
      - `reset_interval_count` integer, nullable, required
    - `components` PlanComponent[], required
      - `billable_metric` Metric, required
        - `metric_id` string, required
        - `event_name` string, required — Name of the event that this metric is tracking.
        - `property_name` string, nullable, required — The name of the property of the event that should be used for this metric. Doesn't apply if the metric is of type 'counter' with an aggregation of count.
        - `aggregation_type` string, required
        - `granularity` 'seconds' | 'minutes' | 'hours' | 'days' | 'months' | 'quarters' | 'years' | 'total' | 'null', nullable, required — The granularity of the metric. Only applies to metrics of type 'gauge' or 'rate'. * `seconds` - Second * `minutes` - Minute * `hours` - Hour * `days` - Day * `months` - Month * `quarters` - Quarter * `years` - Year * `total` - Total
        - `event_type` 'delta' | 'total' | 'null', nullable, required — Used only for metrics of type 'gauge'. Please refer to our documentation for an explanation of the different types. * `delta` - Delta * `total` - Total
        - `metric_type` 'counter' | 'rate' | 'custom' | 'gauge', required — The type of metric that this is. Please refer to our documentation for an explanation of the different types. * `counter` - Counter * `rate` - Rate * `custom` - Custom * `gauge` - Gauge
        - `metric_name` string, required
        - `numeric_filters` NumericFilter[], required
          - `property_name` string, required
          - `operator` 'gte' | 'gt' | 'eq' | 'lt' | 'lte', required — * `gte` - Greater than or equal to * `gt` - Greater than * `eq` - Equal to * `lt` - Less than * `lte` - Less than or equal to
          - `comparison_value` number, double, required
        - `categorical_filters` CategoricalFilter[], required
          - `property_name` string, required
          - `operator` 'isin' | 'isnotin', required — * `isin` - Is in * `isnotin` - Is not in
          - `comparison_value` string[], required
        - `is_cost_metric` boolean, required — Whether or not this metric is a cost metric (used to track costs to your business).
        - `custom_sql` string, nullable, required — A custom SQL query that can be used to define the metric. Please refer to our documentation for more information.
        - `proration` 'seconds' | 'minutes' | 'hours' | 'days' | 'months' | 'quarters' | 'years' | 'total' | 'null', nullable, required — The proration of the metric. Only applies to metrics of type 'gauge'. * `seconds` - Second * `minutes` - Minute * `hours` - Hour * `days` - Day * `months` - Month * `quarters` - Quarter * `years` - Year * `total` - Total
      - `tiers` PriceTier[], required
        - `type` 'flat' | 'per_unit' | 'free', required — * `flat` - flat * `per_unit` - per_unit * `free` - free
        - `range_start` number, double, required
        - `range_end` number, double, nullable, required
        - `cost_per_batch` number, double, nullable, required
        - `metric_units_per_batch` number, double, nullable, required
        - `batch_rounding_type` unknown, required
      - `pricing_unit` PricingUnit, required
        - `code` string, required
        - `name` string, required
        - `symbol` string, required
      - `invoicing_interval_unit` 'day' | 'week' | 'month' | 'year' | 'null', nullable, required — * `day` - day * `week` - week * `month` - month * `year` - year
      - `invoicing_interval_count` integer, nullable, required
      - `reset_interval_unit` 'day' | 'week' | 'month' | 'year' | 'null', nullable, required — * `day` - day * `week` - week * `month` - month * `year` - year
      - `reset_interval_count` integer, nullable, required
      - `prepaid_charge` ComponentCharge, required
        - `units` number, double, nullable, required — The number of units to charge for. If left null, then it will be required at subscription create time.
        - `charge_behavior` 'prorate' | 'full', required — * `prorate` - prorate * `full` - full
    - `features` Feature[], required
      - `feature_id` string, required
      - `feature_name` string, required
      - `feature_description` string, nullable, required
    - `price_adjustment` PriceAdjustment, required
      - `price_adjustment_name` string, required
      - `price_adjustment_description` string, nullable, required
      - `price_adjustment_type` 'percentage' | 'fixed' | 'price_override', required — * `percentage` - Percentage * `fixed` - Fixed * `price_override` - Price Override
      - `price_adjustment_amount` number, double, required
    - `version` union, required
      - integer
      - 'custom_version'
    - `status` 'active' | 'retiring' | 'grandfathered' | 'deleted' | 'inactive' | 'not_started', required — * `active` - Active * `retiring` - Retiring * `grandfathered` - Grandfathered * `deleted` - Deleted * `inactive` - Inactive * `not_started` - Not Started
    - `plan_name` string, required
    - `currency` PricingUnit, required
      - `code` string, required
      - `name` string, required
      - `symbol` string, required
    - `active_from` string, date-time, nullable, required
    - `active_to` string, date-time, nullable, required
    - `localized_name` string, nullable, required
    - `target_customers` LightweightCustomer[], required
      - `customer_name` string, nullable, required — The display name of the customer
      - `email` string, email, nullable, 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
      - `customer_id` string, nullable, required — The id provided when creating the customer, we suggest matching with your internal customer id in your backend
    - `created_on` string, date-time, required
    - `usage_billing_frequency` string, nullable, required
    - `flat_fee_billing_type` 'in_advance' | 'in_arrears', required — * `in_advance` - in_advance * `in_arrears` - in_arrears
    - `flat_rate` number, double, required
    - `description` string, nullable, required
  - `status` string, required — [DEPRECATED] The status of this plan.

---

[API](https://skmtc.net/uselotus/apis/lotus-api.md) · [All operations](https://skmtc.net/uselotus/apis/lotus-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/uselotus/lotus-api/versions/1f59f4fea13f/schema)