> ## 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. # Attach an Add-On > Add an addon to a customer's subscription ```py Python theme={null} lotus.attach_addon( subscription_id='sub_e953bfbf42a442ca90079c8f1656d306', addon_id='addon_5af61a194ca144478fb2721dd34c9049', quantity=3, ) ``` ```ts Typescript theme={null} await lotus.attachAddon({ subscription_id: "sub_e953bfbf42a442ca90079c8f1656d306", addon_id: "addon_5af61a194ca144478fb2721dd34c9049", quantity: 3, }); ``` ## OpenAPI ````yaml POST /api/subscriptions/{subscription_id}/addons/attach/ 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/{subscription_id}/addons/attach/: post: tags: - api operationId: api_subscriptions_addons_attach_create parameters: - in: path name: subscription_id schema: type: string description: The ID of the subscription to add an addon to. required: true requestBody: content: application/json: schema: $ref: '#/components/schemas/AddOnSubscriptionRecordCreateRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/AddOnSubscriptionRecordCreateRequest' multipart/form-data: schema: $ref: '#/components/schemas/AddOnSubscriptionRecordCreateRequest' responses: '200': content: application/json: schema: $ref: '#/components/schemas/AddOnSubscriptionRecord' description: '' security: - knoxTokenAuth: [] - OrganizationApiKeyAuth: [] TokenAuth: [] components: schemas: AddOnSubscriptionRecordCreateRequest: type: object properties: addon_id: type: string format: uuid description: 'The add-on to be applied to the subscription. ' quantity: type: integer minimum: 1 default: 1 description: >- The quantity of the add-on to be applied to the subscription. Flat fees of add-ons will be multiplied by this quantity. Usage-based components of add-ons will be unaffected by the quantity. metadata: type: object additionalProperties: {} description: >- A JSON object containing additional information about the add-on subscription. This will be returned in the response when you retrieve the add-on subscription. AddOnSubscriptionRecord: type: object properties: addon_subscription_id: type: string customer: $ref: '#/components/schemas/LightweightCustomer' addon: $ref: '#/components/schemas/LightweightAddOn' 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. parent: $ref: '#/components/schemas/LightweightSubscriptionRecord' fully_billed: type: boolean readOnly: true auto_renew: type: boolean readOnly: true description: Whether the subscription automatically renews. Defaults to true. metadata: type: object additionalProperties: {} readOnly: true required: - addon - addon_subscription_id - auto_renew - customer - end_date - fully_billed - metadata - parent - start_date 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 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 LightweightSubscriptionRecord: type: object properties: fully_billed: type: boolean readOnly: true plan_detail: allOf: - $ref: '#/components/schemas/LightweightPlanVersion' readOnly: true subscription_id: type: string metadata: type: object additionalProperties: {} subscription_filters: type: array items: $ref: '#/components/schemas/SubscriptionFilter' readOnly: true addons: type: array items: $ref: '#/components/schemas/LightweightAddOnSubscriptionRecord' is_new: type: boolean description: >- Whether this subscription came from a renewal or from a first-time. Defaults to true on creation. customer: $ref: '#/components/schemas/LightweightCustomer' billing_plan: $ref: '#/components/schemas/LightweightPlanVersion' 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. required: - addons - auto_renew - billing_plan - customer - end_date - fully_billed - is_new - metadata - plan_detail - start_date - subscription_filters - subscription_id 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 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 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 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 ````