> ## 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.
# Add Subscription Add-on
> Attach an existing plan to a subscription as a priced add-on with a quantity, billed from the next recurring invoice.
Attaches an existing [plan](/api-reference/plans/get) to a subscription as an
add-on. The subscription's base plan is unchanged; the add-on is billed as an
extra line — add-on plan price × `quantity`, taxed independently — starting
from the **next** recurring invoice. Nothing is charged now and no mid-cycle
proration is applied in v1.
The add-on plan's currency must match the subscription's base-plan currency.
List what is attached with
[List Subscription Add-ons](/api-reference/subscriptions/addons-list) and
detach with
[Remove Subscription Add-on](/api-reference/subscriptions/addons-remove).
## Path Parameters
| Parameter | Type | Required | Description |
| --------- | ------------- | -------- | -------------------- |
| `id` | string (uuid) | Yes | The subscription ID. |
## Request Body
| Parameter | Type | Required | Description |
| ---------- | ------------- | -------- | ---------------------------------------------------------------------------------- |
| `plan_id` | string (uuid) | Yes | The plan to attach as an add-on. Must have a price in the subscription's currency. |
| `quantity` | integer | Yes | Units billed each period. Minimum `1`. |
## Example Request
```bash theme={null}
curl -X POST https://api.recurso.dev/v1/subscriptions/b9071c55-0e14-4720-80f3-665613ceb7de/addons \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"plan_id": "4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8",
"quantity": 3
}'
```
## Response
Returns `201 Created` with the new add-on.
```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 — pass it as `addonId` 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 |
The first invoice carrying the add-on line is the next renewal. To bill an
add-on for the remainder of the current period, change the plan instead —
preview the proration with
[Preview Plan Change](/api-reference/subscriptions/preview-change).
## Errors
| Status | Code | When | Fix |
| ------ | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| 400 | `validation_failed` | `id` is not a valid UUID, the body fails binding (`plan_id` missing or not a UUID, `quantity` missing or below `1`), or the add-on plan's currency does not match the subscription's currency. | Send a valid UUID and a `quantity` of at least `1`; pick a plan priced in the subscription's currency. |
| 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, or `plan_id` does not resolve to a plan with at least one price. | Verify the subscription with `GET /v1/subscriptions/{id}` and the plan with `GET /v1/plans/{id}`. |
Errors use the standard envelope — see [Errors](/api-reference/errors).
## OpenAPI
````yaml POST /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:
post:
tags:
- Subscriptions
summary: Attach an add-on plan to a subscription
description: >
Attaches an existing plan to the subscription as a priced add-on with a
quantity. The subscription's base plan is unchanged; the add-on is
billed as an extra line (add-on plan price × quantity, taxed
independently) starting from the NEXT recurring invoice. The add-on
plan's currency must match the subscription's base-plan currency.
Mid-cycle proration is not applied in v1.
operationId: addSubscriptionAddon
parameters:
- $ref: '#/components/parameters/PathID'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- plan_id
- quantity
properties:
plan_id:
type: string
format: uuid
description: The plan to attach as an add-on.
quantity:
type: integer
minimum: 1
responses:
'201':
description: Add-on attached.
content:
application/json:
schema:
type: object
properties:
data:
$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`.
````