> ## Documentation Index > Fetch the complete documentation index at: https://docs.uselotus.io/llms.txt > Use this file to discover all available pages before exploring further. # Get Plan Retrieves a plan object. ```py Python theme={null} lotus.get_plan( plan_id='plan_0569173ee6654369', ) ``` ```ts Typescript theme={null} await lotus.getPlan({ plan_id: "plan_0569173ee6654369", }); // Will return a promise ``` *** ## OpenAPI ````yaml GET /api/plans/{plan_id}/ openapi: 3.0.3 info: title: Lotus API version: 0.9.3 description: >- Lotus is an open-core pricing and billing engine. We enable API companies to automate and optimize their custom usage-based pricing for any metric. servers: [] security: [] paths: /api/plans/{plan_id}/: get: tags: - api operationId: api_plans_retrieve parameters: - in: path name: plan_id schema: type: string format: uuid required: true - in: query name: version_currency_code schema: type: string minLength: 1 description: >- Filter to versions that have the currency specified by this currency code. - in: query name: version_custom_type schema: enum: - custom_only - public_only - all type: string default: all minLength: 1 description: >- 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 - in: query name: version_status schema: type: array items: enum: - active - ended - not_started type: string description: |- * `active` - Active * `ended` - Ended * `not_started` - Not Started default: - active - not_started - ended description: >- 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. responses: '200': content: application/json: schema: $ref: '#/components/schemas/Plan' description: '' security: - knoxTokenAuth: [] - OrganizationApiKeyAuth: [] TokenAuth: [] components: schemas: Plan: type: object properties: plan_id: type: string plan_name: type: string description: Name of the plan plan_duration: enum: - monthly - quarterly - yearly - null type: string nullable: true description: |- Duration of the plan * `monthly` - Monthly * `quarterly` - Quarterly * `yearly` - Yearly plan_description: type: string nullable: true description: Description of the plan external_links: type: array items: $ref: '#/components/schemas/InitialExternalPlanLink' description: The external links that this plan has. num_versions: type: integer readOnly: true description: The number of versions that this plan has. active_version: type: integer readOnly: true description: This plan's currently active version. active_subscriptions: type: integer readOnly: true description: >- The number of active subscriptions that this plan has across all versions. tags: type: array items: type: string pattern: ^[-a-zA-Z0-9_]+$ readOnly: true description: The tags that this plan has. versions: type: array items: $ref: '#/components/schemas/PlanVersion' description: This plan's versions. parent_plan: allOf: - $ref: '#/components/schemas/PlanNameAndID' nullable: true readOnly: true description: '[DEPRECATED] The parent plan that this plan has.' deprecated: true target_customer: allOf: - $ref: '#/components/schemas/LightweightCustomer' nullable: true readOnly: true description: '[DEPRECATED] The target customer that this plan has.' deprecated: true display_version: allOf: - $ref: '#/components/schemas/PlanVersion' readOnly: true description: >- [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. deprecated: true status: type: string readOnly: true description: '[DEPRECATED] The status of this plan.' deprecated: true required: - active_subscriptions - active_version - display_version - external_links - num_versions - plan_description - plan_duration - plan_id - plan_name - status - tags - versions - parent_plan - target_customer InitialExternalPlanLink: type: object properties: source: enum: - stripe - braintree type: string description: |- * `stripe` - Stripe * `braintree` - Braintree external_plan_id: type: string maxLength: 100 required: - external_plan_id - source PlanVersion: type: object properties: recurring_charges: type: array items: $ref: '#/components/schemas/RecurringCharge' readOnly: true components: type: array items: $ref: '#/components/schemas/PlanComponent' features: type: array items: $ref: '#/components/schemas/Feature' price_adjustment: allOf: - $ref: '#/components/schemas/PriceAdjustment' nullable: true version: oneOf: - type: integer - enum: - custom_version type: string readOnly: true status: enum: - active - retiring - grandfathered - deleted - inactive - not_started type: string description: |- * `active` - Active * `retiring` - Retiring * `grandfathered` - Grandfathered * `deleted` - Deleted * `inactive` - Inactive * `not_started` - Not Started readOnly: true plan_name: type: string readOnly: true currency: $ref: '#/components/schemas/PricingUnit' active_from: type: string format: date-time readOnly: true nullable: true active_to: type: string format: date-time readOnly: true nullable: true localized_name: type: string nullable: true readOnly: true target_customers: type: array items: $ref: '#/components/schemas/LightweightCustomer' created_on: type: string format: date-time readOnly: true usage_billing_frequency: type: string nullable: true readOnly: true deprecated: true flat_fee_billing_type: enum: - in_advance - in_arrears type: string description: |- * `in_advance` - in_advance * `in_arrears` - in_arrears readOnly: true deprecated: true flat_rate: type: number format: double maximum: 10000000000 minimum: 0 exclusiveMaximum: true readOnly: true deprecated: true description: type: string nullable: true readOnly: true deprecated: true required: - active_from - active_to - components - created_on - currency - description - features - flat_fee_billing_type - flat_rate - localized_name - plan_name - price_adjustment - recurring_charges - status - target_customers - usage_billing_frequency - version PlanNameAndID: type: object properties: plan_name: type: string description: Name of the plan plan_id: type: string required: - plan_id - plan_name LightweightCustomer: type: object properties: customer_name: type: string readOnly: true nullable: true description: The display name of the customer email: type: string format: email readOnly: true nullable: true description: >- 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: type: string readOnly: true nullable: true description: >- The id provided when creating the customer, we suggest matching with your internal customer id in your backend required: - customer_id - customer_name - email RecurringCharge: type: object properties: name: type: string charge_timing: enum: - in_advance - in_arrears type: string description: |- * `in_advance` - in_advance * `in_arrears` - in_arrears readOnly: true charge_behavior: enum: - prorate - full type: string description: |- * `prorate` - prorate * `full` - full readOnly: true amount: type: number format: double maximum: 10000000000 minimum: 0 exclusiveMaximum: true pricing_unit: $ref: '#/components/schemas/PricingUnit' invoicing_interval_unit: enum: - day - week - month - year - null type: string description: |- * `day` - day * `week` - week * `month` - month * `year` - year nullable: true readOnly: true invoicing_interval_count: type: integer maximum: 32767 minimum: 0 nullable: true reset_interval_unit: enum: - day - week - month - year - null type: string description: |- * `day` - day * `week` - week * `month` - month * `year` - year nullable: true readOnly: true reset_interval_count: type: integer maximum: 32767 minimum: 0 nullable: true required: - amount - charge_behavior - charge_timing - invoicing_interval_count - invoicing_interval_unit - name - pricing_unit - reset_interval_count - reset_interval_unit PlanComponent: type: object properties: billable_metric: $ref: '#/components/schemas/Metric' tiers: type: array items: $ref: '#/components/schemas/PriceTier' pricing_unit: $ref: '#/components/schemas/PricingUnit' invoicing_interval_unit: enum: - day - week - month - year - null type: string description: |- * `day` - day * `week` - week * `month` - month * `year` - year nullable: true readOnly: true invoicing_interval_count: type: integer readOnly: true nullable: true reset_interval_unit: enum: - day - week - month - year - null type: string description: |- * `day` - day * `week` - week * `month` - month * `year` - year nullable: true readOnly: true reset_interval_count: type: integer readOnly: true nullable: true prepaid_charge: allOf: - $ref: '#/components/schemas/ComponentCharge' nullable: true required: - billable_metric - invoicing_interval_count - invoicing_interval_unit - prepaid_charge - pricing_unit - reset_interval_count - reset_interval_unit - tiers Feature: type: object properties: feature_id: type: string feature_name: type: string readOnly: true feature_description: type: string nullable: true readOnly: true required: - feature_description - feature_id - feature_name PriceAdjustment: type: object properties: price_adjustment_name: type: string maxLength: 100 price_adjustment_description: type: string nullable: true price_adjustment_type: enum: - percentage - fixed - price_override type: string description: |- * `percentage` - Percentage * `fixed` - Fixed * `price_override` - Price Override price_adjustment_amount: type: number format: double maximum: 10000000000 minimum: -10000000000 exclusiveMaximum: true exclusiveMinimum: true required: - price_adjustment_amount - price_adjustment_description - price_adjustment_name - price_adjustment_type PricingUnit: type: object properties: code: type: string maxLength: 10 name: type: string maxLength: 100 symbol: type: string maxLength: 10 required: - code - name - symbol Metric: type: object properties: metric_id: type: string event_name: type: string readOnly: true description: Name of the event that this metric is tracking. property_name: type: string readOnly: true nullable: true description: >- 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: type: string granularity: enum: - seconds - minutes - hours - days - months - quarters - years - total - null type: string readOnly: true nullable: true description: >- 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: enum: - delta - total - null type: string readOnly: true nullable: true description: >- 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: enum: - counter - rate - custom - gauge type: string readOnly: true description: >- 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: type: string numeric_filters: type: array items: $ref: '#/components/schemas/NumericFilter' categorical_filters: type: array items: $ref: '#/components/schemas/CategoricalFilter' is_cost_metric: type: boolean readOnly: true description: >- Whether or not this metric is a cost metric (used to track costs to your business). custom_sql: type: string readOnly: true nullable: true description: >- A custom SQL query that can be used to define the metric. Please refer to our documentation for more information. proration: enum: - seconds - minutes - hours - days - months - quarters - years - total - null type: string readOnly: true nullable: true description: >- 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 required: - aggregation_type - categorical_filters - custom_sql - event_name - event_type - granularity - is_cost_metric - metric_id - metric_name - metric_type - numeric_filters - property_name - proration PriceTier: type: object properties: type: enum: - flat - per_unit - free description: |- * `flat` - flat * `per_unit` - per_unit * `free` - free readOnly: true range_start: type: number format: double maximum: 10000000000 minimum: 0 exclusiveMaximum: true range_end: type: number format: double maximum: 10000000000 minimum: 0 exclusiveMaximum: true nullable: true cost_per_batch: type: number format: double maximum: 10000000000 minimum: 0 exclusiveMaximum: true nullable: true metric_units_per_batch: type: number format: double maximum: 10000000000 minimum: 0 exclusiveMaximum: true nullable: true batch_rounding_type: enum: - round_up - round_down - round_nearest - no_rounding - null description: |- * `round_up` - round_up * `round_down` - round_down * `round_nearest` - round_nearest * `no_rounding` - no_rounding nullable: true readOnly: true required: - batch_rounding_type - cost_per_batch - metric_units_per_batch - range_end - range_start - type ComponentCharge: type: object properties: units: type: number format: double maximum: 10000000000 minimum: 0 exclusiveMaximum: true nullable: true description: >- The number of units to charge for. If left null, then it will be required at subscription create time. charge_behavior: enum: - prorate - full description: |- * `prorate` - prorate * `full` - full readOnly: true required: - charge_behavior - units NumericFilter: type: object properties: property_name: type: string maxLength: 100 operator: enum: - gte - gt - eq - lt - lte type: string description: |- * `gte` - Greater than or equal to * `gt` - Greater than * `eq` - Equal to * `lt` - Less than * `lte` - Less than or equal to comparison_value: type: number format: double required: - comparison_value - operator - property_name CategoricalFilter: type: object properties: property_name: type: string maxLength: 100 operator: enum: - isin - isnotin type: string description: |- * `isin` - Is in * `isnotin` - Is not in comparison_value: type: array items: type: string required: - comparison_value - operator - property_name securitySchemes: knoxTokenAuth: type: apiKey in: header name: Authorization description: Token-based authentication with required prefix "Token" OrganizationApiKeyAuth: type: apiKey in: header name: X-API-KEY ````