Skip to main content
Beta version

Recurring Billing API is in the Beta phase.

Recurring Billing

Manage recurring plans

Managing a recurring plan allows you to control the details of the goods or services you offer, the amount to be charged, and the frequency at which the consumer is charged (billing cycle).

Before you begin

Refer to recurring plans to learn about the Recurring Billing API features and how to customize plans for your business.

Create a recurring plan

Create a recurring plan by sending a POST request to the /plans endpoint using the following required fields.

Required fields for creating a recurring plan
Field name Description
billingFrequencyCount The number of times the plan is billed during the selected billing frequency.
billingFrequencyUnit

Selection of a billing frequency option. The valid values are:

  • DAY
  • WEEK
  • MONTH
  • YEAR

Create a quarterly recurring plan with billingFrequencyUnit set to MONTH and billingFrequencyCount set to 3.

Create a biweekly recurring plan with billingFrequencyUnit set to WEEK and billingFrequencyCount set to 2.
currencyCode Represents a unique identifier for currencies, as assigned by the ISO 4217 specification. It must also be supported by your configured presentment currencies.
planAmount Monetary value charged during each billing cycle of a recurring payment.
planName Uniquely identifies a plan that you manage for a recurring payment, including plan pricing and plan billing frequency.
planType

Identifies the recurring billing model associated with the plan. Determines trial, renewal, and enrollment behavior.

The following plan types are supported:

  • Subscription: An ongoing recurring service or membership. Auto-renew defaults to true. Trials are allowed.
  • Installment: The plan has a fixed number of payments, and totalBillingCycleCount becomes mandatory. Recurring payments created from it are forced to autoRenew: false. Trials are not allowed.
  • Deferred: Billing begins on a specified future date and then follows the configured frequency. A future startDate is required when creating the recurring payment, not when creating the plan. Trials are not allowed.

HTTP method: POST

Endpoint: /plans

Scenario: Create a monthly subscription with a trial

Request:

Json
{
  "merchantPlanId": "PDP-PLAN-1789063578",
  "planName": "PDP Monthly Premium",
  "planStatus": "DRAFT",
  "planType": "SUBSCRIPTION",
  "planAmount": 2999,
  "currencyCode": "USD",
  "billingFrequencyCount": 1,
  "billingFrequencyUnit": "MONTH",
  "billingDayOfMonth": 1,
  "autoRenew": true,
  "totalBillingCycleCount": 12,
  "setupFeeAmount": 0,
  "trialConfiguration": {
    "trialDays": 14,
    "requiresPaymentMethod": true,
    "maxTrialsPerCustomer": 1,
    "offerStartDate": "2026-07-01",
    "offerEndDate": "2026-12-31",
    "reminderDaysBefore": 3,
    "subscriptionActivateInd": true
  }
}

Response:

Json
{
  "autoRenew": true,
  "billingDayOfMonth": 1,
  "billingFrequencyCount": 1,
  "billingFrequencyUnit": "MONTH",
  "createdAt": "2026-09-10T18:06:18.891022Z",
  "currencyCode": "USD",
  "merchantPlanId": "PDP-PLAN-1789063578",
  "planAmount": 2999,
  "planId": "d1ae9795-1dfa-44c8-93c0-b0914b12c0f6",
  "planName": "PDP Monthly Premium",
  "planResponseStatus": "DRAFT",
  "planType": "SUBSCRIPTION",
  "setupFeeAmount": 0,
  "statusLastUpdatedAt": "2026-09-10T18:06:18.890842Z",
  "totalBillingCycleCount": 12,
  "trialConfiguration": {
    "maxTrialsPerCustomer": 1,
    "offerEndDate": "2026-12-31",
    "offerStartDate": "2026-07-01",
    "reminderDaysBefore": 3,
    "requiresPaymentMethod": true,
    "subscriptionActivateInd": true,
    "trialDays": 14
  },
  "updatedAt": "2026-09-10T18:06:18.930083Z"
}

Update a recurring plan

You can update an existing plan by sending a PATCH request to the /plans endpoint. 

Note

Updating an ARCHIVED plan is not allowed because it is in a terminal state.

HTTP method: PATCH

Endpoint: /plans/{planId}

Scenario: Update a draft plan with the planAmount

Request:

Json
{
  "planName": "PDP Monthly Premium - Updated",
  "planAmount": 3599,
  "currencyCode": "USD",
  "autoRenew": true,
  "totalBillingCycleCount": 12
}

Response:

Json
{
  "autoRenew": true,
  "billingDayOfMonth": 1,
  "billingFrequencyCount": 1,
  "billingFrequencyUnit": "MONTH",
  "createdAt": "2026-09-10T14:11:16.984805Z",
  "currencyCode": "USD",
  "merchantPlanId": "PDP-PLAN-1789049476",
  "planAmount": 3599,
  "planId": "f6365310-4152-47f3-8a2c-4d05e24e1d3b",
  "planName": "PDP Monthly Premium - Updated",
  "planResponseStatus": "DRAFT",
  "planType": "SUBSCRIPTION",
  "setupFeeAmount": 0,
  "statusLastUpdatedAt": "2026-09-10T18:27:48.173239Z",
  "totalBillingCycleCount": 12,
  "trialConfiguration": {
    "maxTrialsPerCustomer": 1,
    "offerEndDate": "2026-12-31",
    "offerStartDate": "2026-07-01",
    "reminderDaysBefore": 3,
    "requiresPaymentMethod": true,
    "subscriptionActivateInd": true,
    "trialDays": 14
  },
  "updatedAt": "2026-09-10T18:27:48.206240Z"
}

Retrieve a list of plans

Retrieve the details of recurring plans by sending a GET request to the /plans endpoint. 

Use the following filters to customize your search:

Filters for retrieving a list of plans
Filter Description
currencyCode Exact ISO 4217 currency code.
merchantPlanId Filter by merchant-provided plan ID.
pageNumber Zero-based page index. Default 0.
pageSize Records per page. Default 20; valid range 1-100
planAmount Exact plan amount in minor currency units.
status Filter by planResponseStatus field. Allowed values — DRAFT, ACTIVE, ARCHIVED.
sortOrder Defines the direction in which the result set is displayed. Default is createdAt, DESC. 

HTTP method: GET

Endpoint: /plans

Scenario: Retrieve a list of plans by filtering the status field to DRAFT. The response includes all plans with planResponseStatus set to DRAFT.

Response:

Json
{
  "pageNumber": 0,
  "pageSize": 20,
  "recurringPlanList": [
    {
      "autoRenew": true,
      "billingDayOfMonth": 1,
      "billingFrequencyCount": 1,
      "billingFrequencyUnit": "MONTH",
      "createdAt": "2026-09-10T18:06:18.891022Z",
      "currencyCode": "USD",
      "merchantPlanId": "PDP-PLAN-1789063578",
      "planAmount": 2999,
      "planId": "d1ae9795-1dfa-44c8-93c0-b0914b12c0f6",
      "planName": "PDP Monthly Premium",
      "planResponseStatus": "DRAFT",
      "planType": "SUBSCRIPTION",
      "setupFeeAmount": 0,
      "statusLastUpdatedAt": "2026-09-10T18:06:18.890842Z",
      "totalBillingCycleCount": 12,
      "trialConfiguration": {
        "maxTrialsPerCustomer": 1,
        "offerEndDate": "2026-12-31",
        "offerStartDate": "2026-07-01",
        "reminderDaysBefore": 3,
        "requiresPaymentMethod": true,
        "subscriptionActivateInd": true,
        "trialDays": 14
      },
      "updatedAt": "2026-09-10T18:06:18.930083Z"
    },
    {
      "autoRenew": true,
      "billingDayOfMonth": 1,
      "billingFrequencyCount": 1,
      "billingFrequencyUnit": "MONTH",
      "createdAt": "2026-09-10T13:42:28.313548Z",
      "currencyCode": "USD",
      "merchantPlanId": "PDP-PLAN-1789047748",
      "planAmount": 2999,
      "planId": "189416a7-768b-4291-a99a-cddb4dfba680",
      "planName": "PDP Monthly Premium",
      "planResponseStatus": "DRAFT",
      "planType": "SUBSCRIPTION",
      "setupFeeAmount": 0,
      "statusLastUpdatedAt": "2026-09-10T13:42:28.313350Z",
      "totalBillingCycleCount": 12,
      "trialConfiguration": {
        "maxTrialsPerCustomer": 1,
        "offerEndDate": "2026-12-31",
        "offerStartDate": "2026-07-01",
        "reminderDaysBefore": 3,
        "requiresPaymentMethod": true,
        "subscriptionActivateInd": true,
        "trialDays": 14
      },
      "updatedAt": "2026-09-10T13:42:28.366193Z"
    }
  ]
}

Retrieve a specific plan

You can retrieve the details of recurring plans by sending a GET request to the /plans endpoint. 

HTTP method: GET

Endpoint: /plans/{planId}

Scenario: Retrieve a specific plan

Response:

Json
{
  "autoRenew": true,
  "billingDayOfMonth": 1,
  "billingFrequencyCount": 1,
  "billingFrequencyUnit": "MONTH",
  "createdAt": "2026-09-10T14:11:16.984805Z",
  "currencyCode": "USD",
  "merchantPlanId": "PDP-PLAN-1789049476",
  "planAmount": 3599,
  "planId": "f6365310-4152-47f3-8a2c-4d05e24e1d3b",
  "planName": "PDP Monthly Premium - Updated",
  "planResponseStatus": "ACTIVE",
  "planType": "SUBSCRIPTION",
  "setupFeeAmount": 0,
  "statusLastUpdatedAt": "2026-09-10T18:23:15.652294Z",
  "totalBillingCycleCount": 12,
  "trialConfiguration": {
    "maxTrialsPerCustomer": 1,
    "offerEndDate": "2026-12-31",
    "offerStartDate": "2026-07-01",
    "reminderDaysBefore": 3,
    "requiresPaymentMethod": true,
    "subscriptionActivateInd": true,
    "trialDays": 14
  },
  "updatedAt": "2026-09-10T18:23:15.674810Z"
}

Perform a lifecycle action on a plan

Recurring billing supports the following lifecycle actions on a plan.

Lifecycle action
Lifecycle actions Description Allowed current status Resulting status Additional restrictions
ACTIVATE

Makes a draft plan available for recurring-payment enrollment.

DRAFT

 ACTIVE Fails if already ACTIVE. An ARCHIVED plan cannot be activated.
DEACTIVATE Removes an active plan from use and returns it to DRAFT.  ACTIVE DRAFT All associated recurring payments must be terminal. 
ARCHIVE Permanently retires a plan. DRAFT or ACTIVE ARCHIVED All associated recurring payments must be terminal. Already archived plans fail. ARCHIVED is terminal and cannot be activated or deactivated.

HTTP method: POST

Endpoint: /plans/{planId}/actions?recurringPlanStatusCode=DEACTIVATE

Scenario: Deactivate a plan so it moves from ACTIVE to DRAFT

Response:

Json
{
  "autoRenew": true,
  "billingDayOfMonth": 1,
  "billingFrequencyCount": 1,
  "billingFrequencyUnit": "MONTH",
  "createdAt": "2026-09-10T13:22:39.759045Z",
  "currencyCode": "USD",
  "merchantPlanId": "PDP-PLAN-1789046559",
  "planAmount": 3499,
  "planId": "cae24ef6-3a75-47b8-80bd-4dbb73dd2c38",
  "planName": "PDP Monthly Premium - Updated",
  "planResponseStatus": "DRAFT",
  "planType": "SUBSCRIPTION",
  "setupFeeAmount": 0,
  "statusLastUpdatedAt": "2026-09-10T13:23:24.345840Z",
  "totalBillingCycleCount": 12,
  "trialConfiguration": {
    "maxTrialsPerCustomer": 1,
    "offerEndDate": "2026-12-31",
    "offerStartDate": "2026-07-01",
    "reminderDaysBefore": 3,
    "requiresPaymentMethod": true,
    "subscriptionActivateInd": true,
    "trialDays": 14
  },
  "updatedAt": "2026-09-10T13:23:24.358920Z"
}

Recurring plans

Recurring payments

Is this page helpful?