> ## Documentation Index > Fetch the complete documentation index at: https://docs.recurso.dev/llms.txt > Use this file to discover all available pages before exploring further. # List Subscription Add-ons > List the add-on plans attached to a subscription, with their quantities. Returns every add-on currently attached to a subscription. Each add-on is an existing plan billed as an extra line — add-on plan price × `quantity`, taxed independently — on the subscription's recurring invoices. Attach one with [Add Subscription Add-on](/api-reference/subscriptions/addons-add) and detach with [Remove Subscription Add-on](/api-reference/subscriptions/addons-remove). The list is not paginated; a subscription with no add-ons returns an empty array. ## Path Parameters | Parameter | Type | Required | Description | | --------- | ------------- | -------- | -------------------- | | `id` | string (uuid) | Yes | The subscription ID. | ## Example Request ```bash theme={null} curl https://api.recurso.dev/v1/subscriptions/b9071c55-0e14-4720-80f3-665613ceb7de/addons \ -H "Authorization: Bearer $API_KEY" ``` ## Response ```json theme={null} { "data": [ { "id": "d3a7f1c2-5b8e-4c90-a6d1-2e3f4a5b6c7d", "tenant_id": "0f9e8d7c-6b5a-4f3e-9d2c-1b0a9f8e7d6c", "subscription_id": "b9071c55-0e14-4720-80f3-665613ceb7de", "plan_id": "4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8", "quantity": 3, "created_at": "2026-08-20T09:15:00Z" } ] } ``` ## Fields | Field | Type | Description | | ----------------- | ------------------ | ------------------------------------------- | | `id` | string (uuid) | The add-on ID — use it to remove the add-on | | `tenant_id` | string (uuid) | Owning tenant | | `subscription_id` | string (uuid) | The subscription the add-on is attached to | | `plan_id` | string (uuid) | The plan billed as an add-on | | `quantity` | integer | Number of add-on units billed each period | | `created_at` | string (date-time) | When the add-on was attached | ## Errors | Status | Code | When | Fix | | ------ | ------------------- | --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | | 400 | `validation_failed` | `id` is not a valid UUID. | Pass the subscription's UUID. | | 401 | `unauthorized` | API key missing or invalid (`invalid_api_key`), or a live/test mode mismatch (`key_mode_mismatch`). | Send `Authorization: Bearer ` with a key for the right mode. | | 404 | `not_found` | The subscription does not exist in your tenant (cross-tenant IDs also return 404). | Verify the ID with `GET /v1/subscriptions/{id}`. | Errors use the standard envelope — see [Errors](/api-reference/errors). ## OpenAPI ````yaml GET /v1/subscriptions/{id}/addons openapi: 3.1.0 info: title: Recurso API version: 1.0.0 description: | The Recurso billing engine REST API. Authenticate by passing your API key as a bearer token: Authorization: Bearer Obtain an API key by registering a tenant via `POST /auth/register`. All authenticated endpoints live under the `/v1` prefix. Mutating endpoints support idempotency via the `Idempotency-Key` header. license: name: MIT identifier: MIT servers: - url: https://billing.example.com description: >- Example deployment — substitute the base URL of your own Recurso deployment. security: - bearerAuth: [] tags: - name: System description: Health, version, and API metadata - name: Auth description: Tenant registration - name: Plans description: Product catalog plans - name: Customers description: Customer management - name: Subscriptions description: Subscription lifecycle - name: Invoices description: Invoices, PDFs, and Indian GST e-invoicing - name: Coupons description: Discounts - name: Usage description: Metered usage events - name: Credit Notes description: Customer credits - name: Quotes description: Quote-to-invoice lifecycle - name: Webhooks description: Webhook endpoint management and event feed - name: Analytics description: Revenue analytics - name: Checkout description: Public hosted checkout for invoices - name: Payments description: Payment order creation - name: Inbound Webhooks description: Receivers for payment-gateway callbacks (Razorpay, Stripe) - name: Customer Portal description: Customer-facing portal — magic-link auth and session-scoped data - name: Developer description: API key management - name: Account description: Tenant account settings - name: Finance description: Ledger accounts, entries, reconciliation, and revenue recognition - name: Settings description: Tax (GST) and e-invoicing (IRP) configuration - name: Consents description: Consent records for RBI-compliant recurring billing - name: Referrals description: Customer referral program - name: Gifts description: Gift subscriptions - name: Mandates description: UPI Autopay mandates - name: Offline Payments description: Virtual accounts and manually recorded payments - name: Organizations description: Multi-entity organizations grouping several tenants - name: Accounting description: QuickBooks / Xero accounting integrations - name: Churn description: Churn risk scoring and alerts - name: Cancel Flows description: Configurable retention flows shown at cancellation time - name: Dunning description: Dunning analytics and multi-channel dunning campaigns paths: /v1/subscriptions/{id}/addons: get: tags: - Subscriptions summary: List a subscription's add-ons operationId: listSubscriptionAddons parameters: - $ref: '#/components/parameters/PathID' responses: '200': description: Add-ons attached to the subscription. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/SubscriptionAddon' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' components: parameters: PathID: name: id in: path required: true schema: type: string format: uuid schemas: SubscriptionAddon: type: object description: > An existing plan attached to a subscription with a quantity (Multi-product catalog v1). Billed as an extra line — add-on plan price × quantity, taxed independently — from the subscription's next recurring invoice. properties: id: type: string format: uuid tenant_id: type: string format: uuid subscription_id: type: string format: uuid plan_id: type: string format: uuid description: The plan billed as an add-on. quantity: type: integer description: Number of add-on units billed each period. created_at: type: string format: date-time Error: type: object required: - error properties: error: type: object description: Structured error detail. required: - code - message properties: code: type: string description: Stable machine-readable error code. examples: - validation_failed - unauthorized - forbidden - not_found - conflict - rate_limited - internal_error - invalid_api_key - key_mode_mismatch - over_refund - invoice_not_paid - invoice_already_paid message: type: string description: Human-readable explanation. responses: BadRequest: description: The request body or parameters are invalid. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Missing or invalid credentials (API key or session cookie). content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API key description: >- Tenant API key obtained from `POST /auth/register` or `POST /v1/developer/keys`. ````