End-to-End Billing Flow

The Happy Path

This guide walks through the complete happy path of billing a customer with Recurso. By the end, you will have created a plan, added a customer, started a subscription, and collected payment — with webhooks firing at each stage.

Step 1: Create a Plan

Define what you are selling and how much it costs.

curl -X POST https://api.recurso.dev/v1/plans \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pro Plan",
    "code": "pro-monthly-inr",
    "interval_unit": "month",
    "interval_count": 1,
    "amount": 499900,
    "currency": "INR"
  }'

Response:

{
  "data": {
    "id": "plan_pro01",
    "name": "Pro Plan",
    "code": "pro-monthly-inr",
    "interval_unit": "month",
    "interval_count": 1,
    "prices": [
      { "amount": 499900, "currency": "INR", "type": "recurring" }
    ],
    "active": true
  }
}

Save the id — you will use it in step 3.

For pricing model options (flat rate, per-seat, tiered, usage-based), see the Plans guide.

Step 2: Create a Customer

Add the person or company who will be billed.

curl -X POST https://api.recurso.dev/v1/customers \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation",
    "email": "billing@acme.com",
    "phone": "+919876543210",
    "billing_address": {
      "line1": "123 MG Road",
      "city": "Bangalore",
      "state": "Karnataka",
      "postal_code": "560001",
      "country": "IN"
    }
  }'

Response:

{
  "data": {
    "id": "cust_acme01",
    "name": "Acme Corporation",
    "email": "billing@acme.com"
  }
}

Save the id for the next step.

For B2B customers in India, include the gstin field to get GST-compliant invoices. See the GST Invoicing guide.

Step 3: Create a Subscription

Connect the customer to the plan. This starts the billing relationship.

curl -X POST https://api.recurso.dev/v1/subscriptions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_acme01",
    "plan_id": "plan_pro01"
  }'

Response:

{
  "data": {
    "id": "sub_xyz789",
    "customer_id": "cust_acme01",
    "plan_id": "plan_pro01",
    "status": "active",
    "current_period_start": "2026-06-24T00:00:00Z",
    "current_period_end": "2026-07-24T00:00:00Z"
  }
}

Activation issues the first invoice. Fetch it (GET /v1/invoices?subscription_id=...) and send the customer to the hosted checkout page — https://api.recurso.dev/checkout/{invoice_id} — where Recurso picks the gateway from the invoice currency. (With a saved UPI mandate or card on file, collection is automatic instead.) After payment succeeds, Recurso fires these webhooks:

Webhook: `subscription.created`

{
  "type": "subscription.created",
  "data": {
    "id": "sub_xyz789",
    "customer_id": "cust_acme01",
    "plan_id": "plan_pro01",
    "status": "active",
    "current_period_start": "2026-06-24T00:00:00Z",
    "current_period_end": "2026-07-24T00:00:00Z"
  }
}

Webhook: `payment.succeeded`

{
  "type": "payment.succeeded",
  "data": {
    "id": "pay_001",
    "invoice_id": "inv_001",
    "amount": 589882,
    "currency": "INR",
    "gateway": "razorpay"
  }
}

Grant access to your product when you receive subscription.created. See the Webhooks guide for signature verification.

Step 4: Invoice Auto-Generated

At the end of each billing period, Recurso automatically generates the next invoice. No API call is needed from your side.

Webhook: `invoice.created`

{
  "type": "invoice.created",
  "data": {
    "id": "inv_002",
    "invoice_number": "REC/2026/0002",
    "customer_id": "cust_acme01",
    "subscription_id": "sub_xyz789",
    "status": "open",
    "currency": "INR",
    "subtotal": 499900,
    "tax_amount": 89982,
    "total": 589882,
    "due_date": "2026-08-08T00:00:00Z"
  }
}

You can fetch any invoice at any time:

curl https://api.recurso.dev/v1/invoices?customer_id=cust_acme01 \
  -H "Authorization: Bearer $API_KEY"

Step 5: Payment Collected

Recurso charges the customer’s saved payment method automatically. On success:

Webhook: `invoice.paid`

{
  "type": "invoice.paid",
  "data": {
    "id": "inv_002",
    "status": "paid",
    "amount_paid": 589882,
    "paid_at": "2026-07-24T00:05:00Z"
  }
}

If payment fails, Recurso enters the dunning flow — retrying payment on a configurable schedule and sending reminder emails to the customer.

Webhook: `invoice.payment_failed`

{
  "type": "invoice.payment_failed",
  "data": {
    "id": "inv_002",
    "status": "past_due",
    "next_retry_at": "2026-07-25T00:00:00Z"
  }
}

Step 6: Subscription Renews

After payment succeeds, the subscription period advances automatically:

current_period_start moves to the start of the new period
current_period_end moves forward by one billing interval
A new invoice is generated at the next period end

This cycle repeats until the subscription is canceled or paused.

What Happens Next

Once the basic flow is running, you can layer on additional features:

Add Coupons

Apply discounts to subscriptions at creation time

Usage Billing

Add metered billing on top of flat-rate plans

Customer Portal

Let customers self-manage subscriptions and invoices

Webhooks

Set up production webhook endpoints with signature verification

Smart Retry

Configure intelligent payment retry logic

Go to Production

Switch from test to live keys and prepare for launch

Get Started

Migrate to Recurso

Core Concepts

Usage & Monetization

Money & Books

Tax & Compliance

Recover & Retain

Customer Portal

Platform & Integrations

Deploy & Operate

Reference

End-to-End Billing Flow

The Happy Path

Step 1: Create a Plan

Step 2: Create a Customer

Step 3: Create a Subscription

Webhook: `subscription.created`

Webhook: `payment.succeeded`

Step 4: Invoice Auto-Generated

Webhook: `invoice.created`

Step 5: Payment Collected

Webhook: `invoice.paid`

Webhook: `invoice.payment_failed`

Step 6: Subscription Renews

What Happens Next

Add Coupons

Usage Billing

Customer Portal

Webhooks

Smart Retry

Go to Production

​The Happy Path

​Step 1: Create a Plan

​Step 2: Create a Customer

​Step 3: Create a Subscription

​Webhook: subscription.created

​Webhook: payment.succeeded

​Step 4: Invoice Auto-Generated

​Webhook: invoice.created

​Step 5: Payment Collected

​Webhook: invoice.paid

​Webhook: invoice.payment_failed

​Step 6: Subscription Renews

​What Happens Next

Add Coupons

Usage Billing

Customer Portal

Webhooks

Smart Retry

Go to Production

The Happy Path

Step 1: Create a Plan

Step 2: Create a Customer

Step 3: Create a Subscription

Webhook: `subscription.created`

Webhook: `payment.succeeded`

Step 4: Invoice Auto-Generated

Webhook: `invoice.created`

Step 5: Payment Collected

Webhook: `invoice.paid`

Webhook: `invoice.payment_failed`

Step 6: Subscription Renews

What Happens Next