> ## 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.
# Set Subscription Commitment
> Set or clear the per-period minimum commitment on a subscription, in minor units; shortfalls are trued up on the renewal invoice.
Sets the subscription's per-period minimum commitment. When a period's
subtotal (flat fee + add-ons + metered usage) falls short of the commitment, a
**Minimum commitment true-up** line fills exactly the difference on the renewal
invoice, taxed at the plan's HSN. Usage beyond the floor bills naturally. An
`amount` of `0` clears the commitment.
The commitment is stored on the subscription as `commitment_amount` and
returned by [Get Subscription](/api-reference/subscriptions/get). For the
concept and setup walkthrough see
[Set Up Minimum Commitments](/setup/commitments).
## Path Parameters
| Parameter | Type | Required | Description |
| --------- | ------------- | -------- | -------------------- |
| `id` | string (uuid) | Yes | The subscription ID. |
## Request Body
| Parameter | Type | Required | Description |
| --------- | --------------- | -------- | --------------------------------------------------------------------------------------------------------- |
| `amount` | integer (int64) | Yes | Per-period minimum in minor units of the subscription's currency. Minimum `0`; `0` clears the commitment. |
## Example Request
```bash theme={null}
curl -X PUT https://api.recurso.dev/v1/subscriptions/b9071c55-0e14-4720-80f3-665613ceb7de/commitment \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"amount": 500000
}'
```
## Response
Returns the updated subscription.
```json theme={null}
{
"data": {
"id": "b9071c55-0e14-4720-80f3-665613ceb7de",
"tenant_id": "0f9e8d7c-6b5a-4f3e-9d2c-1b0a9f8e7d6c",
"customer_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"plan_id": "7c0e2b91-3f5a-4d8c-a2b4-1e9f0d6c5a83",
"status": "active",
"current_period_start": "2026-09-01T00:00:00Z",
"current_period_end": "2026-10-01T00:00:00Z",
"cancel_at_period_end": false,
"billing_anchor": "2026-09-01T00:00:00Z",
"billing_anchor_type": "acquisition",
"billing_anchor_day": 1,
"payment_terms": "net0",
"commitment_amount": 500000,
"razorpay_subscription_id": "",
"stripe_subscription_id": "",
"created_at": "2026-03-01T10:30:00Z",
"updated_at": "2026-09-04T10:30:00Z"
}
}
```
## Fields
| Field | Type | Description |
| --------------------------------------------- | ------------------ | --------------------------------------------------------------------- |
| `id` | string (uuid) | The subscription ID |
| `customer_id` | string (uuid) | The billed customer |
| `plan_id` | string (uuid) | The base plan |
| `status` | string | Subscription status (`trialing`, `active`, `paused`, `canceled`, …) |
| `current_period_start` / `current_period_end` | string (date-time) | The current billing period |
| `commitment_amount` | integer (int64) | The per-period minimum just set, minor units; `0` means no commitment |
| `updated_at` | string (date-time) | Bumped by this call |
Other fields are the standard subscription object — see
[Get Subscription](/api-reference/subscriptions/get).
Nothing is invoiced when the commitment is set. The true-up line, if any, is
computed at renewal against that period's actual subtotal, so the invoice
always shows both the usage billed and the exact shortfall filled.
## Errors
| Status | Code | When | Fix |
| ------ | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| 400 | `validation_failed` | `id` is not a valid UUID, `amount` is missing or negative, the body is malformed JSON, or the subscription does not exist in your tenant (this endpoint reports a missing subscription as `400`, not `404`). | Pass the subscription's UUID and an integer `amount` of `0` or more; verify the ID with `GET /v1/subscriptions/{id}`. |
| 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. |
Errors use the standard envelope — see [Errors](/api-reference/errors).
## OpenAPI
````yaml PUT /v1/subscriptions/{id}/commitment
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}/commitment:
put:
tags:
- Subscriptions
summary: Set the per-period minimum commitment
description: >-
Minor units. When a period's subtotal (flat + add-ons + metered usage)
falls short of the commitment, a "Minimum commitment true-up" line fills
exactly the difference on the renewal invoice, taxed at the plan HSN.
Usage beyond the floor bills naturally. Amount 0 clears the commitment.
operationId: setSubscriptionCommitment
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- amount
properties:
amount:
type: integer
format: int64
minimum: 0
responses:
'200':
description: The updated subscription
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/Subscription'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
components:
schemas:
Subscription:
type: object
properties:
id:
type: string
format: uuid
tenant_id:
type: string
format: uuid
customer_id:
type: string
format: uuid
plan_id:
type: string
format: uuid
status:
$ref: '#/components/schemas/SubscriptionStatus'
current_period_start:
type: string
format: date-time
current_period_end:
type: string
format: date-time
cancel_at_period_end:
type: boolean
canceled_at:
type: string
format: date-time
cancellation_reason:
type: string
cancellation_feedback:
type: string
billing_anchor:
type: string
format: date-time
billing_anchor_type:
type: string
billing_anchor_day:
type: integer
payment_terms:
type: string
coupon_id:
type: string
format: uuid
reference_id:
type: string
mandate_id:
type: string
format: uuid
razorpay_subscription_id:
type: string
stripe_subscription_id:
type: string
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
SubscriptionStatus:
type: string
enum:
- trialing
- active
- past_due
- paused
- canceled
- unpaid
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'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API key
description: >-
Tenant API key obtained from `POST /auth/register` or `POST
/v1/developer/keys`.
````