Recurring Payment

Set up subscription plans that auto-generate and auto-bill orders on a schedule. Define billing cycles with custom intervals, handle proration for mid-cycle starts, and configure retry logic and grace periods for failed payments. The system handles the calendar — you define the rules.

Workflow

The recommended order of operations to set up and run a subscription.

1. Create a customerAPI . You need the customer_uuid to bind the plan.

2. Create a recurring itemAPI with label, price and currency. Items are reusable across plans.

3. Create a recurring billing configAPI to define the billing rhythm - billing_interval, interval_count and billing_proration_enabled.

4. Create a recurring planAPI to bind the customer, billing config, item, and retry settings together. Define multiple cycles — like a free trial followed by paid billing — in one API call.

5. Share the recurring payment link from the recurring plan's first order with the customer. The customer completes the first payment, and their card is automatically saved as a payment_token.

6. The system auto-generates and auto-bills a new recurring order on each billing date using the saved token. Query plan lever ordersAPI or individual recurring orderAPI through the API.

Recurring item

A recurring item is a product or service that will be billed on each cycle. Items are created once and can be reused across multiple plans.

Recurring billing config

A billing config defines the rhythm and rules for when invoices are generated. Configs are reusable — create one and assign it to multiple plans.

POST /svc/payment/api/v1/openapi/recurring_payments/billing_configs
{
  "config": {
    "billing_interval": "monthly",
    "interval_count": 1,
    "billing_type": "automated",
    "billing_proration_enabled": true,
    "description": "Monthly billing - prorated first cycle"
  }
}

Recurring plan

A plan binds a customer to a set of items and billing rules. It controls how payments are collected and what happens when a charge fails.

Recurring cycle

An ordered list of billing phases within a plan. Each cycle has its own billing config, items, and duration — cycles execute sequentially, one after the other (e.g. a 1-month free trial cycle followed by an indefinite annual cycle).

Examples

Related APIs

Create an itemAPI

Define a recurring product with a label, price, and currency. Items are reusable — create once, reference in multiple plans.

Create a billing configAPI

Define a billing schedule with interval, count, billing type, and proration settings. Configs are reusable across plans.

Create a planAPI

Create a recurring plan with customer, billing config, items, and retry settings. Define multiple cycles in one call. The response includes a current_payment_link to share with the customer for the first payment.

Get itemsAPI
Get billing configsAPI

List all recurring items or billing configs. Use the Advanced query DSLDOC for filtering and pagination.

Delete an itemAPI
Delete a billing configAPI

Remove an item or billing config. Ensure no active plan references the resource before deleting.

Get recurring plansAPI
Get a recurring planAPI

List all plans or get a single plan by ID. The response includes the plan details, active cycles, current order, and linked customer.

Add plan cyclesAPI

Add new cycles to an existing plan (upgrade/downgrade/extend). Choose immediate, next_billing_date, or as_last_cycle activation timing.

Cancel a planAPI

Cancel all active cycles of a plan. Choose immediate or next_billing_date. Optionally refund remaining credit.

Get plan ordersAPI
Get a recurring orderAPI

Query all orders generated by a plan, or get a single recurring order by ID. Use the Advanced query DSLDOC for filtering.