Subscriptions

What Subscriptions Automate

Subscriptions connect customers to plans and handle the billing cycle automatically. Recurso manages:

Recurring invoicing
Payment collection
Trial periods
Proration for upgrades/downgrades
Dunning for failed payments

Create a Subscription

const subscription = await recurso.subscriptions.create({
  customer_id: '9f2c1e84-6a3d-4b7e-9c21-8f4a5d6e7b01',
  plan_id: '3e7a9c52-1b4d-4f8e-a6c3-2d5b8e9f0a14'
});

// The first invoice is issued when the subscription activates.
// Fetch it, then collect on the hosted checkout page (gateway
// chosen by invoice currency) — or let a saved mandate autopay it:
const { data: invoices } = await recurso.invoices.list({
  subscription_id: subscription.id,
});
const payLink = `https://api.recurso.dev/checkout/${invoices[0].id}`;

curl -X POST https://api.recurso.dev/v1/subscriptions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "9f2c1e84-6a3d-4b7e-9c21-8f4a5d6e7b01",
    "plan_id": "3e7a9c52-1b4d-4f8e-a6c3-2d5b8e9f0a14"
  }'

from uuid import UUID

from recurso.api.invoices import list_invoices
from recurso.api.subscriptions import create_subscription
from recurso.models import CreateSubscriptionRequest

subscription = create_subscription.sync(
    client=client,
    body=CreateSubscriptionRequest(
        customer_id=UUID("9f2c1e84-6a3d-4b7e-9c21-8f4a5d6e7b01"),
        plan_id=UUID("3e7a9c52-1b4d-4f8e-a6c3-2d5b8e9f0a14"),
    ),
)

# The first invoice is issued when the subscription activates.
invoices = list_invoices.sync(client=client, subscription_id=subscription.id)
pay_link = f"https://api.recurso.dev/checkout/{invoices.data[0].id}"

subscription, _ := client.Subscriptions.Create(ctx, &recurso.SubscriptionCreateParams{
  CustomerID: "9f2c1e84-6a3d-4b7e-9c21-8f4a5d6e7b01",
  PlanID:     "3e7a9c52-1b4d-4f8e-a6c3-2d5b8e9f0a14",
})

// The first invoice is issued when the subscription activates.
invoices, _ := client.Invoices.List(ctx, &recurso.InvoiceListParams{
  SubscriptionID: subscription.ID,
})
payLink := "https://api.recurso.dev/checkout/" + invoices[0].ID

There is no gateway parameter here: Recurso routes each payment to the right gateway from the invoice currency and your gateway connections, and payment happens per invoice — on the hosted checkout page or automatically via a saved mandate.

Apply a Coupon at Creation

Apply a discount coupon when creating a subscription:

const subscription = await recurso.subscriptions.create({
  customer_id: '9f2c1e84-6a3d-4b7e-9c21-8f4a5d6e7b01',
  plan_id: '3e7a9c52-1b4d-4f8e-a6c3-2d5b8e9f0a14',
  coupon_code: 'LAUNCH20'  // 20% off first 3 months
});

The coupon discount is applied to invoices for the duration specified in the coupon configuration. See the Coupons guide for creating and managing coupons.

Subscription Lifecycle

Status	Description
`created`	Awaiting first payment
`trialing`	In free trial period
`active`	Active and paid
`paused`	Billing temporarily suspended; no invoices generated
`past_due`	Payment failed, in dunning
`canceled`	Subscription ended

Free Trials

Start customers with a free trial:

// Plan-level trial
const plan = await recurso.plans.create({
  name: 'Pro',
  trial_days: 14,
  ...
});

// Or subscription-level override
const subscription = await recurso.subscriptions.create({
  customer_id: 'cust_abc123',
  plan_id: 'plan_pro',
  trial_end: new Date('2024-02-15')  // Custom trial end
});

During trial, no invoice is generated. The first invoice is created when trial ends.

Per-Seat Quantities (Add-ons)

Subscriptions don’t carry a bare quantity — seats are modeled as an add-on: an existing plan attached to the subscription with a quantity, billed as its own line (add-on price × quantity, taxed independently) from the next recurring invoice:

# 10 seats of the per-seat plan on top of the base plan
curl -X POST https://api.recurso.dev/v1/subscriptions/{sub_id}/addons \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "plan_id": "plan_seat", "quantity": 10 }'

Seats that fluctuate mid-period are often better metered: a billable metric with max(seats) aggregation bills the period’s high-water mark with no proration bookkeeping — see usage-based billing.

Upgrade / Downgrade

Change plans mid-cycle:

await recurso.subscriptions.update('sub_xyz', {
  plan_id: 'plan_enterprise',
  proration_behavior: 'create_prorations'  // default
});

// Proration options:
// - 'create_prorations': Credit remaining time, charge new plan
// - 'none': No proration, change at next renewal
// - 'always_invoice': Invoice immediately

How Proration Works

When a customer upgrades mid-cycle with create_prorations:

Recurso calculates a credit for the unused portion of the current plan
Recurso calculates the charge for the new plan for the remaining period
The net difference appears as a line item on the next invoice

Example: Customer upgrades from ₹4,999/mo to ₹9,999/mo on day 15 of a 30-day cycle:

Credit for old plan: ₹4,999 × (15/30) = ₹2,499.50
Charge for new plan: ₹9,999 × (15/30) = ₹4,999.50
Net charge on next invoice: ₹2,500.00

Want to see the exact number for your own prices? The Proration page has a live calculator that runs the same math the API uses, plus how to preview any plan change with a single API call.

Cancel Subscription

At Period End (Recommended)

await recurso.subscriptions.cancel('sub_xyz', {
  cancel_at_period_end: true
});

// subscription.status remains 'active'
// subscription.cancel_at_period_end = true
// Customer retains access until current_period_end

Immediately

await recurso.subscriptions.cancel('sub_xyz', {
  immediately: true
});

// subscription.status = 'canceled'
// Access revoked immediately
// Optionally prorate and refund

For advanced cancellation flows with retention offers, see the Cancel Flows guide.

Reactivate a Canceled Subscription

If a subscription was canceled with cancel_at_period_end: true and the period has not yet ended, you can reactivate it:

await recurso.subscriptions.reactivate('sub_xyz');

// subscription.cancel_at_period_end = false
// Billing resumes as normal at next renewal

curl -X POST https://api.recurso.dev/v1/subscriptions/sub_xyz/reactivate \
  -H "Authorization: Bearer $API_KEY"

from recurso.api.subscriptions import reactivate_subscription

# id is the subscription's UUID
result = reactivate_subscription.sync(subscription.id, client=client)

# cancel_at_period_end is cleared; billing resumes at next renewal

result, _ := client.Subscriptions.Reactivate(ctx, "sub_xyz")

// cancel_at_period_end is cleared; billing resumes at next renewal

Reactivation is only possible while the subscription is still active (before current_period_end). Once the status changes to canceled, you must create a new subscription.

Pause Subscription

Temporarily pause billing:

await recurso.subscriptions.pause('sub_xyz', {
  resume_at: new Date('2024-03-01')
});

// subscription.status = 'paused'
// No invoices generated until resumed

Billing Anchor

Control when subscriptions bill. The billing anchor determines which day of the month the subscription renews.

Acquisition Date (Default)

By default, the billing anchor is the day the subscription was created. A subscription created on the 15th renews on the 15th of each month.

Fixed Date (First of Month)

For enterprise customers who need invoices on a consistent date:

const subscription = await recurso.subscriptions.create({
  customer_id: 'cust_abc123',
  plan_id: 'plan_pro',
  billing_anchor: 1  // Always bill on 1st of month
});

When the billing anchor differs from the subscription start date, the first period is prorated. For example, a subscription starting on January 15 with billing_anchor: 1 generates a prorated invoice for January 15-31, then full invoices from February 1 onward.

Use billing_anchor for enterprise customers who need invoices on specific dates.

Payment Terms

Configure when invoices are due relative to when they are generated:

const subscription = await recurso.subscriptions.create({
  customer_id: 'cust_abc123',
  plan_id: 'plan_enterprise',
  payment_terms: 'net30'  // Due 30 days after invoice date
});

Term	Due Date
`net0`	Due immediately (same day as invoice)
`net15`	Due 15 days after invoice date
`net30`	Due 30 days after invoice date
`net60`	Due 60 days after invoice date

Payment terms are commonly used for enterprise and B2B subscriptions where customers need time to process payments through their accounts payable workflow.

UPI Mandates

For Indian customers paying via UPI, you can set up a UPI mandate for automatic recurring payments:

const subscription = await recurso.subscriptions.create({
  customer_id: '9f2c1e84-6a3d-4b7e-9c21-8f4a5d6e7b01',
  plan_id: '3e7a9c52-1b4d-4f8e-a6c3-2d5b8e9f0a14'
});

// Mandates are their own resource — register one against the
// subscription and renewals collect automatically:
const mandate = await recurso.mandates.create({
  customer_id: subscription.customer_id,
  subscription_id: subscription.id,
  vpa: 'customer@upi',
  max_amount: 999900,        // per-debit cap, minor units (₹9,999.00)
  frequency: 'monthly'
});

The customer authorizes the mandate once, and subsequent payments are charged automatically. See the UPI Mandates guide for setup details. Track customer consent for billing-related communications:

const subscription = await recurso.subscriptions.create({
  customer_id: 'cust_abc123',
  plan_id: 'plan_pro',
  consent: {
    billing_emails: true,
    marketing_emails: false,
    auto_renewal: true
  }
});

See the Consent Tracking guide for compliance requirements.

Get Subscription

const subscription = await recurso.subscriptions.get('sub_xyz');

// Returns
{
  id: 'sub_xyz',
  customer_id: 'cust_abc123',
  plan: { id: 'plan_pro', name: 'Pro Plan', ... },
  status: 'active',
  current_period_start: '2024-01-01T00:00:00Z',
  current_period_end: '2024-02-01T00:00:00Z',
  cancel_at_period_end: false,
  invoices: [...]
}

List Subscriptions

const subscriptions = await recurso.subscriptions.list({
  customer_id: 'cust_abc123',  // Filter by customer
  status: 'active',            // Filter by status
  limit: 20
});

Webhooks

Subscribe to subscription events:

Event	Description
`subscription.created`	New subscription
`subscription.created`	First payment succeeded
`subscription.updated`	Plan changed
`subscription.canceled`	Subscription canceled
`subscription.past_due`	Payment failed

Get Started

Migrate to Recurso

Core Concepts

Usage & Monetization

Money & Books

Tax & Compliance

Recover & Retain

Customer Portal

Platform & Integrations

Deploy & Operate

Reference

What Subscriptions Automate

Create a Subscription

Apply a Coupon at Creation

Subscription Lifecycle

Free Trials

Per-Seat Quantities (Add-ons)

Upgrade / Downgrade

How Proration Works

Cancel Subscription

At Period End (Recommended)

Immediately

Reactivate a Canceled Subscription

Pause Subscription

Billing Anchor

Acquisition Date (Default)

Fixed Date (First of Month)

Payment Terms

UPI Mandates

Get Subscription

List Subscriptions

Webhooks

Next steps

Invoices

Usage-based billing

​What Subscriptions Automate

​Create a Subscription

​Apply a Coupon at Creation

​Subscription Lifecycle

​Free Trials

​Per-Seat Quantities (Add-ons)

​Upgrade / Downgrade

​How Proration Works

​Cancel Subscription

​At Period End (Recommended)

​Immediately

​Reactivate a Canceled Subscription

​Pause Subscription

​Billing Anchor

​Acquisition Date (Default)

​Fixed Date (First of Month)

​Payment Terms

​UPI Mandates

​Consent Tracking

​Get Subscription

​List Subscriptions

​Webhooks

​Next steps

Invoices

Usage-based billing

What Subscriptions Automate

Create a Subscription

Apply a Coupon at Creation

Subscription Lifecycle

Free Trials

Per-Seat Quantities (Add-ons)

Upgrade / Downgrade

How Proration Works

Cancel Subscription

At Period End (Recommended)

Immediately

Reactivate a Canceled Subscription

Pause Subscription

Billing Anchor

Acquisition Date (Default)

Fixed Date (First of Month)

Payment Terms

UPI Mandates

Consent Tracking

Get Subscription

List Subscriptions

Webhooks

Next steps