> ## 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. # List subscriptions Retrieves an array of `subscription` objects. ```py Python theme={null} lotus.list_subscriptions(customer_id="cust_id") ``` ```ts Typescript theme={null} await lotus.listSubscriptions({ customerId: "cust_id" }); ``` ## OpenAPI ````yaml GET /api/subscriptions/ 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/subscriptions/: get: tags: - api operationId: api_subscriptions_list parameters: - in: query name: customer_id schema: type: string nullable: true minLength: 1 description: Filter to a specific customer. required: true - in: query name: plan_id schema: type: string format: uuid description: Filter to a specific plan. - in: query name: range_end schema: type: string format: date-time description: >- If specified, will only return subscriptions with a start date before this date. - in: query name: range_start schema: type: string format: date-time description: >- If specified, will only return subscriptions with an end date after this date. - in: query name: status schema: type: array items: enum: - active - ended - not_started type: string description: |- * `active` - Active * `ended` - Ended * `not_started` - Not Started default: - active description: >- Filter to a specific set of subscription statuses. Defaults to active. - in: query name: subscription_filters schema: type: array items: $ref: '#/components/schemas/SubscriptionFilterRequest' description: >- Filter to a specific set of subscription filters. If your billing model only allows for one subscription per customer, you very likely do not need this field. Must be formatted as a JSON-encoded + stringified list of dictionaries, where each dictionary has a key of 'property_name' and a key of 'value'. responses: '200': content: application/json: schema: type: array items: $ref: '#/components/schemas/SubscriptionRecord' description: '' security: - knoxTokenAuth: [] - OrganizationApiKeyAuth: [] TokenAuth: [] components: schemas: SubscriptionFilterRequest: type: object properties: value: type: string minLength: 1 property_name: type: string minLength: 1 description: 'The string name of the property to filter on. Example: ''product_id''' required: - property_name - value SubscriptionRecord: type: object properties: subscription_id: type: string start_date: type: string format: date-time description: >- The time the subscription starts. This will be a string in yyyy-mm-dd HH:mm:ss format in UTC time. end_date: type: string format: date-time description: >- The time the subscription starts. This will be a string in yyyy-mm-dd HH:mm:ss format in UTC time. auto_renew: type: boolean description: Whether the subscription automatically renews. Defaults to true. is_new: type: boolean description: >- Whether this subscription came from a renewal or from a first-time. Defaults to true on creation. subscription_filters: type: array items: $ref: '#/components/schemas/SubscriptionFilter' customer: $ref: '#/components/schemas/LightweightCustomer' billing_plan: $ref: '#/components/schemas/LightweightPlanVersion' fully_billed: type: boolean readOnly: true addons: type: array items: $ref: '#/components/schemas/LightweightAddOnSubscriptionRecord' metadata: type: object additionalProperties: {} required: - addons - auto_renew - billing_plan - customer - end_date - fully_billed - is_new - metadata - start_date - subscription_filters - subscription_id SubscriptionFilter: type: object properties: value: type: string property_name: type: string description: 'The string name of the property to filter on. Example: ''product_id''' required: - property_name - value 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 LightweightPlanVersion: type: object properties: plan_name: type: string readOnly: true plan_id: type: string version_id: type: string readOnly: true version: oneOf: - type: integer - enum: - custom_version type: string readOnly: true required: - plan_id - plan_name - version - version_id LightweightAddOnSubscriptionRecord: type: object properties: addon_subscription_id: type: string start_date: type: string format: date-time readOnly: true description: >- The time the subscription starts. This will be a string in yyyy-mm-dd HH:mm:ss format in UTC time. end_date: type: string format: date-time readOnly: true description: >- The time the subscription starts. This will be a string in yyyy-mm-dd HH:mm:ss format in UTC time. addon: $ref: '#/components/schemas/LightweightAddOn' fully_billed: type: boolean readOnly: true required: - addon - addon_subscription_id - end_date - fully_billed - start_date LightweightAddOn: type: object properties: addon_name: type: string description: The name of the add-on plan. addon_id: type: string description: The ID of the add-on plan. addon_type: enum: - flat - usage_based type: string readOnly: true billing_frequency: enum: - one_time - recurring description: |- * `one_time` - one_time * `recurring` - recurring readOnly: true required: - addon_id - addon_name - addon_type - billing_frequency 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 ````