Skip to main content
Beta version

Recurring Billing API is in the Beta phase.

Recurring Billing

Manage recurring payments

Managing recurring payments allows you to create a new recurring payment linked to a recurring billing plan, billing schedule and payment method. 

Before you begin

Learn about recurring payments and the features that the Recurring Billing API provides to help you customize billing for your business.

Create a recurring payment

Create a recurring payment by sending a POST request to the /recurring-payments endpoint using the following important fields:

Required recurring payments fields
Field name Description Restrictions
planId Identifies the plan to enroll in.
  • Required
  • Must exist and be ACTIVE.
paymentMethod Container for the stored payment instrument. Required
paymentMethod.consumerProfile Stored consumer-profile reference. Required
consumerProfile.consumerProfileId Consumer profile containing the payment method. Required
consumerProfile.paymentMethodId Stored payment-method identifier. Required

startDate
  • Cannot be in the past.
  • A deferred plan requires a future date no more than one year away.
 Optional
endDate Cannot precede the start date and is used only when effective auto-renewal is disabled. Optional
Auto-renewal

Defaults to true for eligible plans. Installment plans always disable it.

 Optional
amount
  • Inherited from the plan unless planOverrides.amount is supplied.
  • Override amount must be greater than zero.
 Optional
currencyCode Inherited from the plan unless overridden. Optional
billingFrequencyCount

Inherited from the plan unless count overrides are supplied.

 Optional
billingFrequencyUnit

Inherited from the plan unless unit overrides are supplied.

 Optional
setupFeeAmount The payment override takes precedence over the plan fee and applies to the first cycle only. Optional
taxAmount The supplied tax amount applies to the first cycle and is used to derive tax for later cycles. Optional

HTTP method: POST

Endpoint: /recurring-payments

Scenario: Create a recurring payment linked to a plan and payment method

Request:

Json
{
  "planId": "5dc33cfa-e970-42bd-9962-c231acbaf592",
  "merchantRecurringPaymentId": "PDP-SUB-1789052312",
  "recurringPaymentName": "PDP Recurring Payment",
  "paymentMethod": {
    "consumerProfile": {
      "consumerProfileId": "JPMCW-48U8SENTLJCJU7HE",
      "paymentMethodId": "bdf5af6e-a37e-47d9-959a-28c7424fe5f7",
      "isBillPayment": false,
      "paymentTypeCode": "RECURRING"
    }
  },
  "startDate": "2026-09-10",
  "autoRenew": true,
  "initiatorType": "MERCHANT",
  "taxAmount": 0,
  "planOverrides": {
    "amount": 2999,
    "currencyCode": "USD",
    "billingFrequencyCount": 1,
    "billingFrequencyUnit": "MONTH",
    "totalBillingCycleCount": 12,
    "autoRenew": true
  }
}

Response:

Json
{
  "amount": 2999,
  "autoRenew": true,
  "billingFrequencyCount": 1,
  "billingFrequencyUnit": "MONTH",
  "completedBillingCycleCount": 0,
  "createdAt": "2026-09-10T14:58:32.452359Z",
  "currencyCode": "USD",
  "lastBillingCycleId": "4a9e7e96-0954-4721-a876-1a2d567899ba",
  "merchantRecurringPaymentId": "PDP-SUB-1789052312",
  "nextBillingScheduledDate": "2026-09-10",
  "paymentMethod": {
    "consumerProfile": {
      "consumerProfileId": "JPMCW-48U8SENTLJCJU7HE",
      "isBillPayment": false,
      "paymentMethodId": "bdf5af6e-a37e-47d9-959a-28c7424fe5f7",
      "paymentTypeCode": "RECURRING"
    }
  },
  "planId": "5dc33cfa-e970-42bd-9962-c231acbaf592",
  "planName": "RB Billing Plan 20260825001722577-48399f",
  "planOverrides": {
    "amount": 2999,
    "autoRenew": true,
    "billingDayOfMonth": 15,
    "billingDayOfWeek": 1,
    "billingFrequencyCount": 1,
    "billingFrequencyUnit": "MONTH",
    "billingIntervalDays": 30,
    "currencyCode": "USD",
    "planType": "SUBSCRIPTION",
    "setupFeeAmount": 500,
    "totalBillingCycleCount": 12
  },
  "recurringPaymentId": "c8b06947-f299-41b9-92af-04973be05d17",
  "recurringPaymentName": "PDP Recurring Payment",
  "recurringPaymentStatus": "ACTIVE",
  "remainingBillingCycleCount": 12,
  "skippedBillingCycleCount": 0,
  "startDate": "2026-09-10",
  "statusLastUpdatedAt": "2026-09-10T14:58:32.452083Z",
  "taxAmount": 0,
  "updatedAt": "2026-09-10T14:58:32.806026Z"
}

Update a recurring payment

Update a recurring payment by sending a PATCH request to the /recurring-payments endpoint using the recurringPaymentId field.

The following scenarios describe when a field is eligible for update.

Scenarios for updating a recurring payment
Field name Scenario description
startDate Update the startDate only when the recurringPaymentStatus field is set to SCHEDULED or TRIALING.
endDate

Update the endDate when the recurringPaymentStatus is either in SCHEDULED, ACTIVE, or PAUSED.

Keep in mind that:

  • The endDate cannot be earlier than the current billing cycle start date.
  • If you update the endDate during the recently collected billing cycle and autoRenewal is false, Recurring Billing automatically calculates and stores a pro-rated credit. You can use the stored pro-rated credit to issue a manual refund.
  • If you update the endDate during the recently collected billing cycle and autoRenewal is true, the update is not allowed.
  • If you update the endDate before payment for the next billing cycle is collected, Recurring Billing bills only the pro-rated amount instead of the full cycle amount.
  • If you update the endDate on the billing cycle start date after payment for the cycle is collected, Recurring Billing automatically calculates and stores a full credit. You can use the stored full credit to issue manual refunds.
planId Update the planId regardless of recurringPaymentStatus.
paymentMethodId Update the paymentMethodId to a new payment method or any other existing payment method from the consumer profile at any time during the lifecycle of the recurring payment. If it's a new payment method, Recurring Billing stores it automatically in the consumer profile.

Account verification is done in both scenarios and must be successful for the update to go through.

HTTP method: PATCH

Endpoint: /recurring-payments/{recurringPaymentId}

Scenario: Update the recurring payment with new amount for planOverrides

Request:

Json
{
  "recurringPaymentName": "PDP Recurring Payment - Updated",
  "autoRenew": false,
  "planOverrides": {
    "amount": 3499,
    "currencyCode": "USD"
  }
}

Response:

Json
{
  "amount": 3499,
  "autoRenew": false,
  "billingFrequencyCount": 1,
  "billingFrequencyUnit": "MONTH",
  "completedBillingCycleCount": 1,
  "createdAt": "2026-09-10T14:58:32.452359Z",
  "currencyCode": "USD",
  "lastBillingCycleId": "ca3a84bf-9603-48bd-aee4-fe1785d8505f",
  "merchantRecurringPaymentId": "PDP-SUB-1789052312",
  "nextBillingScheduledDate": "2026-09-09",
  "paymentMethod": {
    "consumerProfile": {
      "consumerProfileId": "JPMCW-48U8SENTLJCJU7HE",
      "isBillPayment": false,
      "originalNetworkTransactionId": "FAK5299990910",
      "paymentMethodId": "bdf5af6e-a37e-47d9-959a-28c7424fe5f7",
      "paymentTypeCode": "RECURRING"
    }
  },
  "planId": "5dc33cfa-e970-42bd-9962-c231acbaf592",
  "planName": "RB Billing Plan 20260825001722577-48399f",
  "planOverrides": {
    "amount": 3499,
    "autoRenew": true,
    "billingDayOfMonth": 15,
    "billingDayOfWeek": 1,
    "billingFrequencyCount": 1,
    "billingFrequencyUnit": "MONTH",
    "billingIntervalDays": 30,
    "currencyCode": "USD",
    "planType": "SUBSCRIPTION",
    "setupFeeAmount": 500,
    "totalBillingCycleCount": 13
  },
  "recurringPaymentId": "c8b06947-f299-41b9-92af-04973be05d17",
  "recurringPaymentName": "PDP Recurring Payment - Updated",
  "recurringPaymentStatus": "ACTIVE",
  "remainingBillingCycleCount": 12,
  "skippedBillingCycleCount": 1,
  "startDate": "2026-09-10",
  "statusLastUpdatedAt": "2026-09-10T14:58:32.452083Z",
  "taxAmount": 0,
  "updatedAt": "2026-09-11T13:25:21.129936Z"
}

Retrieve a recurring payment

HTTP method: GET

Endpoint: /recurring-payments/{recurringPaymentId}

Scenario: Retrieve a recurring payment information by recurringPaymentId = bcbd73ef-27ad-442c-a54d-ee63974fb456

Response:

Json
{
  "amount": 3499,
  "autoRenew": true,
  "billingFrequencyCount": 1,
  "billingFrequencyUnit": "MONTH",
  "completedBillingCycleCount": 0,
  "createdAt": "2026-09-10T01:46:57.665024Z",
  "currencyCode": "USD",
  "lastBillingCycleId": "e27fed8f-63ef-42d9-8a5f-814a820923d1",
  "merchantRecurringPaymentId": "PDP-SUB-1789004817",
  "nextBillingScheduledDate": "2026-10-24",
  "pauseEndDate": "2026-09-10",
  "pauseStartDate": "2026-09-10",
  "paymentMethod": {
    "consumerProfile": {
      "consumerProfileId": "JPMCW-DLHRHME8IJYKD3LK",
      "isBillPayment": false,
      "paymentMethodId": "6217cd2d-bf1d-42a9-a338-5b537686bfbe",
      "paymentTypeCode": "RECURRING"
    }
  },
  "planId": "ef87ab7f-101c-4c39-809a-bcd1acb37ba2",
  "planName": "PDP Monthly Premium - Updated",
  "planOverrides": {
    "amount": 3499,
    "autoRenew": true,
    "billingDayOfMonth": 1,
    "billingFrequencyCount": 1,
    "billingFrequencyUnit": "MONTH",
    "currencyCode": "USD",
    "planType": "SUBSCRIPTION",
    "setupFeeAmount": 0,
    "totalBillingCycleCount": 13
  },
  "recurringPaymentId": "bcbd73ef-27ad-442c-a54d-ee63974fb456",
  "recurringPaymentName": "PDP Recurring Payment - Updated",
  "recurringPaymentStatus": "TRIALING",
  "remainingBillingCycleCount": 13,
  "skippedBillingCycleCount": 1,
  "startDate": "2026-09-10",
  "statusLastUpdatedAt": "2026-09-10T01:48:37.117157Z",
  "taxAmount": 0,
  "updatedAt": "2026-09-10T01:49:04.753006Z"
}

Perform a lifecycle action on a recurring payment

Refer to the following table to understand the lifecycle action rules:

Action rules table
Action Allowed current status Result
PAUSE ACTIVE, SCHEDULED, or TRIALING The status changes to PAUSED immediately or to ACTIVE for a future start.
RESUME PAUSED The status changes to ACTIVE immediately.
CANCEL ACTIVE, PAUSED, SCHEDULED, SUSPENDED, or TRIALING The status changes to CANCELLED.

HTTP method: POST

Endpoint: /recurring-payments/{recurringPaymentId}/actions

Scenario: Perform a lifecycle action of PAUSE on a recurring payment 

Request:

Json
{
  "action": "PAUSE",
  "pauseEndDate": "2026-10-15"
}

Response:

Json
{
  "amount": 2999,
  "autoRenew": true,
  "billingFrequencyCount": 1,
  "billingFrequencyUnit": "MONTH",
  "completedBillingCycleCount": 1,
  "createdAt": "2026-09-08T19:01:09.640746Z",
  "currencyCode": "USD",
  "lastBillingCycleId": "8d231ff0-7734-41a2-94a3-8077fe994faa",
  "merchantRecurringPaymentId": "PDP-SUB-1788894069",
  "nextBillingScheduledDate": "2026-10-08",
  "pauseEndDate": "2026-10-15",
  "pauseStartDate": "2026-09-09",
  "paymentMethod": {
    "consumerProfile": {
      "consumerProfileId": "JPMCW-MNV2ADX25K0W3GBF",
      "isBillPayment": false,
      "originalNetworkTransactionId": "MCW5111000908",
      "paymentMethodId": "42bace37-87ea-47a8-8f09-70e401c11b80",
      "paymentTypeCode": "RECURRING"
    }
  },
  "planId": "ca7b1e4a-81dc-43e8-856d-d772247b96c4",
  "planName": "Dup Check Plan 1788870534283",
  "planOverrides": {
    "amount": 2999,
    "autoRenew": true,
    "billingFrequencyCount": 1,
    "billingFrequencyUnit": "MONTH",
    "currencyCode": "USD",
    "planType": "SUBSCRIPTION",
    "totalBillingCycleCount": 13
  },
  "recurringPaymentId": "c629a798-61be-4f4f-b119-075b07a4c01c",
  "recurringPaymentName": "PDP Recurring Payment",
  "recurringPaymentStatus": "PAUSED",
  "remainingBillingCycleCount": 12,
  "skippedBillingCycleCount": 1,
  "startDate": "2026-09-08",
  "statusLastUpdatedAt": "2026-09-09T19:10:52.915809Z",
  "taxAmount": 0,
  "updatedAt": "2026-09-09T19:10:52.996823Z"
}
Note

If the payment is already PAUSED or has a future pause scheduled, another PAUSE request updates the pause period. In that case, pauseEndDate is required and cannot be in the past.

Retrieve a list of recurring payments

By using the following filters, you can further customize the recurring payments you want to retrieve:

Filter for recurring payments
Filter Description
consumerProfileId Filter recurring payments by consumer profile identifier.
startDate Include payments starting on or after startDate.
endDate Include payments starting on or before startDate.
pageNumber Zero-based page index. Default 0.
pageSize Records per page. Default 20; valid range 1-100
status Filter by recurringPaymentStatus field. Allowed values:  CANCELLED, PAUSED, SCHEDULED, TRIALING, ACTIVE, COMPLETED.

HTTP method: GET

Endpoint: /recurring-payments?status=TRIALING

Scenario: Retrieve a list of recurring payments by filtering the status field to TRIALING. The response includes all recurring payments with recurringPaymentStatus set to TRIALING.

Response:

Json
{
  "pageNumber": 0,
  "pageSize": 20,
  "recurringPaymentList": [
    {
      "amount": 2999,
      "autoRenew": true,
      "billingFrequencyCount": 1,
      "billingFrequencyUnit": "MONTH",
      "completedBillingCycleCount": 0,
      "createdAt": "2026-09-10T14:11:25.454992Z",
      "currencyCode": "USD",
      "lastBillingCycleId": "994e0557-2b22-4dc3-8faa-a978a20c08cb",
      "merchantRecurringPaymentId": "PDP-SUB-1789049485",
      "nextBillingScheduledDate": "2026-09-24",
      "paymentMethod": {
        "consumerProfile": {
          "consumerProfileId": "JPMCW-DLHRHME8IJYKD3LK",
          "isBillPayment": false,
          "paymentMethodId": "6217cd2d-bf1d-42a9-a338-5b537686bfbe",
          "paymentTypeCode": "RECURRING"
        }
      },
      "planId": "f6365310-4152-47f3-8a2c-4d05e24e1d3b",
      "planName": "PDP Monthly Premium - Updated",
      "planOverrides": {
        "amount": 2999,
        "autoRenew": true,
        "billingDayOfMonth": 1,
        "billingFrequencyCount": 1,
        "billingFrequencyUnit": "MONTH",
        "currencyCode": "USD",
        "planType": "SUBSCRIPTION",
        "setupFeeAmount": 0,
        "totalBillingCycleCount": 12
      },
      "recurringPaymentId": "2b42c3a1-e1be-45ef-a83f-304d0fa0728e",
      "recurringPaymentName": "PDP Recurring Payment",
      "recurringPaymentStatus": "TRIALING",
      "remainingBillingCycleCount": 12,
      "skippedBillingCycleCount": 0,
      "startDate": "2026-09-10",
      "statusLastUpdatedAt": "2026-09-10T14:11:25.454827Z",
      "taxAmount": 0,
      "updatedAt": "2026-09-10T14:11:25.658207Z"
    },
    {
      "amount": 10000,
      "autoRenew": true,
      "billingFrequencyCount": 1,
      "billingFrequencyUnit": "MONTH",
      "completedBillingCycleCount": 1,
      "createdAt": "2026-09-10T08:54:47.358898Z",
      "currencyCode": "USD",
      "lastBillingCycleId": "d4e58af3-0961-4bcd-9627-1902439b1dd0",
      "nextBillingScheduledDate": "2026-10-17",
      "paymentMethod": {
        "consumerProfile": {
          "consumerProfileId": "JPMCW-48U8SENTLJCJU7HE",
          "originalNetworkTransactionId": "FAK5299990910",
          "paymentMethodId": "bdf5af6e-a37e-47d9-959a-28c7424fe5f7"
        }
      },
      "planId": "8a11adab-8d72-4c6e-be59-e34ebd23e012",
      "planName": "Enrollment Tax Plan 1789030402820",
      "planOverrides": {
        "amount": 10000,
        "autoRenew": true,
        "billingFrequencyCount": 1,
        "billingFrequencyUnit": "MONTH",
        "currencyCode": "USD",
        "planType": "SUBSCRIPTION",
        "setupFeeAmount": 2000,
        "totalBillingCycleCount": 12
      },
      "recurringPaymentId": "cc099617-f0df-4e89-874f-662efd7315e3",
      "recurringPaymentStatus": "TRIALING",
      "remainingBillingCycleCount": 11,
      "skippedBillingCycleCount": 0,
      "startDate": "2026-09-10",
      "statusLastUpdatedAt": "2026-09-10T08:54:47.358360Z",
      "taxAmount": 1200,
      "updatedAt": "2026-09-10T08:55:06.809944Z"
    },
    {
      "amount": 2000,
      "autoRenew": true,
      "billingFrequencyCount": 1,
      "billingFrequencyUnit": "WEEK",
      "completedBillingCycleCount": 0,
      "createdAt": "2026-09-08T16:36:53.854223Z",
      "currencyCode": "USD",
      "lastBillingCycleId": "0124cfd7-bd64-4333-9d44-96572c5d0c37",
      "nextBillingScheduledDate": "2026-09-15",
      "paymentMethod": {
        "consumerProfile": {
          "consumerProfileId": "JPMCW-0LZ7BJD53ZG5OLUP",
          "paymentMethodId": "e846c032-0eb9-495f-88cc-35cbe8c7cf8a"
        }
      },
      "planId": "14435911-a29b-441c-8a3e-b33d65accf72",
      "planName": "testtrail",
      "planOverrides": {
        "amount": 2000,
        "autoRenew": true,
        "billingFrequencyCount": 1,
        "billingFrequencyUnit": "WEEK",
        "currencyCode": "USD",
        "planType": "SUBSCRIPTION",
        "totalBillingCycleCount": 5
      },
      "recurringPaymentId": "2de279c9-1e42-4569-9a30-825cc953b172",
      "recurringPaymentStatus": "TRIALING",
      "remainingBillingCycleCount": 5,
      "skippedBillingCycleCount": 0,
      "startDate": "2026-09-08",
      "statusLastUpdatedAt": "2026-09-08T16:36:53.853077Z",
      "updatedAt": "2026-09-08T16:36:54.768843Z"
    }
  ]
}

Recurring payments

Is this page helpful?