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

# GET /api/plans/

`GET /api/plans/`

## Query parameters

- `exclude_tags` string[]
- `include_tags` string[]
- `include_tags_all` string[]

## Response `200`

- Plan[]
  - `plan_name` string, required — Name of the plan
  - `plan_duration` 'monthly' | 'quarterly' | 'yearly' | 'null', nullable, required — Duration of the plan
  - `status` 'active' | 'archived' | 'experimental', required
  - `external_links` InitialExternalPlanLink[], required — The external links that this plan has.
    - `source` 'stripe' | 'braintree', required
    - `external_plan_id` string, required
  - `plan_id` string, 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
    - `description` string, nullable, required
    - `flat_fee_billing_type` 'in_advance' | 'in_arrears', required
    - `flat_rate` number, double, required
    - `recurring_charges` RecurringCharge[], required
      - `name` string, required
      - `charge_timing` 'in_advance' | 'in_arrears', required
      - `charge_behavior` 'prorate' | 'full', required
      - `amount` number, double, required
      - `pricing_unit` PricingUnit, required
        - `code` string, required
        - `name` string, required
        - `symbol` string, 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'.
        - `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.
        - `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.
        - `metric_name` string, required
        - `numeric_filters` NumericFilter[], required
          - `property_name` string, required
          - `operator` 'gte' | 'gt' | 'eq' | 'lt' | 'lte', required
          - `comparison_value` number, double, required
        - `categorical_filters` CategoricalFilter[], required
          - `property_name` string, required
          - `operator` 'isin' | 'isnotin', required
          - `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'.
      - `tiers` PriceTier[], required
        - `type` 'flat' | 'per_unit' | 'free', required
        - `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
    - `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
      - `price_adjustment_amount` number, double, required
    - `usage_billing_frequency` 'monthly' | 'quarterly' | 'end_of_period' | 'null', nullable, required
    - `version` integer, required
    - `status` 'active' | 'retiring' | 'grandfathered' | 'archived' | 'inactive', required
    - `plan_name` string, required
    - `currency` PricingUnit, required
      - `code` string, required
      - `name` string, required
      - `symbol` string, required
  - `num_versions` integer, required — The number of versions that this plan has.
  - `active_subscriptions` integer, required — The number of active subscriptions that this plan has across all versions.
  - `tags` Tag[], required — The tags that this plan has.
    - `tag_name` string, required
    - `tag_hex` string, nullable
    - `tag_color` string, nullable

## Changes

- **2023-02-20** `d246ebbb528d` — 1 breaking
  - the response property `items/target_customer/allOf[#/components/schemas/LightweightCustomer]/customer_id` became nullable for the status `200`
- **2023-02-19** `33a8ac13f9bf` — 1 info
  - the `items/target_customer/allOf[#/components/schemas/LightweightCustomer]/customer_id` response's property pattern `^[-a-zA-Z0-9_]+$` was removed for the status `200`
- **2023-02-18** `59a3ecddd82c` — 3 info
  - added the new optional `query` request parameter `exclude_tags`
  - added the new optional `query` request parameter `include_tags`
  - added the new optional `query` request parameter `include_tags_all`
- **2023-02-15** `ff677a692b91` — 1 warning
  - added the new `braintree` enum value to the `items/external_links/items/source` response property for the response status `200`
- **2023-02-14** `54ca4f2cceaa` — 1 info
  - the response required property `items/display_version/recurring_charges` became read-only for the status `200`

[Full history](https://skmtc.dev/uselotus/apis/lotus-api/changes/api/plans/get.md)

---

[API](https://skmtc.dev/uselotus/apis/lotus-api.md) · [All operations](https://skmtc.dev/uselotus/apis/lotus-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/uselotus/lotus-api/revisions/d246ebbb528d/schema)