> ## 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.

# Create a subscription

> Add a plan to a customer's subscription

A subscription associates one of your customers with one of your billing plans. You can safely give a customer multiple subscriptions to different plans.

If you want to give a single customer multiple subscriptions to the same plan (for example, one for each of their environments), you can do that using `subscription_filters`. For more details on how to use them and what they do, see the [subscription filters](../../plan-management/creating-plans#plan-components) documentation.

If any of your usage components has a [prepaid charge](../../plan-management/creating-plans#plan-components) associated with it, you can specify how many units they prepaid for as part of this call. If you don't specify a value, the component's default value will be used. If there was no default value, the susbcription creation will fail.

<CodeGroup>
  ```py Python theme={null}
  lotus.create_subscription(
    customer_id='cust_6c237d6c149c47db8f64246b78ecac13',
    plan_id='plan_f17c6153807d4f4b812265a09cf06680',
    start_date='2022-02-23 03:30:00+00:00',
  )
  ```

  ```ts Typescript theme={null}
  await lotus.createSubscription({
    customer_id: "cust_6c237d6c149c47db8f64246b78ecac13",
    plan_id: "plan_f17c6153807d4f4b812265a09cf06680",
    start_date: "2022-02-23 03:30:00+00:00",
  });
  ```
</CodeGroup>


## OpenAPI

````yaml POST /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/:
    post:
      tags:
        - api
      operationId: api_subscriptions_create
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionRecordCreateRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/SubscriptionRecordCreateRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/SubscriptionRecordCreateRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionRecord'
          description: ''
      security:
        - knoxTokenAuth: []
        - OrganizationApiKeyAuth: []
          TokenAuth: []
components:
  schemas:
    SubscriptionRecordCreateRequest:
      type: object
      properties:
        start_date:
          type: string
          format: date-time
          description: >-
            The date the subscription starts. This should be a string in
            YYYY-MM-DD format of the date in UTC time.
        end_date:
          type: string
          format: date-time
          description: >-
            The date the subscription ends. This should be a string in
            YYYY-MM-DD format of the date in UTC time. If you don’t set it
            (recommended), we will use the information in the billing plan to
            automatically calculate this.
        auto_renew:
          type: boolean
          description: Whether the subscription automatically renews. Defaults to true.
        is_new:
          type: boolean
        subscription_filters:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionFilterRequest'
          description: >-
            Add filter key, value pairs that define which events will be applied
            to this plan subscription.
        customer_id:
          type: string
          nullable: true
          minLength: 1
          description: The id provided when creating the customer
          writeOnly: true
        plan_id:
          type: string
          format: uuid
          writeOnly: true
          nullable: true
          description: >-
            The Lotus plan_id, found in the billing plan object. We will make a
            best-effort attempt to find the correct plan version (matching
            preferred currencies, prioritizing custom plans), but if more than
            one plan version or no plan version matches these criteria this will
            return an error.
        component_fixed_charges_initial_units:
          type: array
          items:
            $ref: '#/components/schemas/ComponentsFixedChargeInitialValueRequest'
          description: >-
            The initial units for the plan components' prepaid fixed charges.
            This is only required if the plan has plan components where you did
            not specify the initial units.
        metadata:
          type: object
          additionalProperties: {}
          description: >-
            A JSON object containing additional information about the
            subscription.
      required:
        - customer_id
        - start_date
    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
    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
    ComponentsFixedChargeInitialValueRequest:
      type: object
      properties:
        metric_id:
          type: string
          format: uuid
          writeOnly: true
          description: The id of the metric that this initial value is for
        units:
          type: number
          format: double
          maximum: 10000000000
          minimum: 0
          exclusiveMaximum: true
          description: The number of units of the metric that this initial value is for
      required:
        - metric_id
        - units
    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

````