Skip to main content
Beta version

Recurring Billing API is in the Beta phase.

Recurring Billing

Manage billing cycles

A recurring billing cycle provides visibility into the individual billing events generated for a recurring payment. Use these endpoints to retrieve billing cycle details, monitor payment and retry activity, manage billing cycle status, manually collect past-due payments, and issue full or partial refunds when needed.

Retrieve a specific billing cycle

HTTP method: GET

Endpoint: /billing-cycles/{billingCycleId}

Scenario: Retrieving billing cycles by billingCycleId

Response:

Json
{
  "billingCycleId": "23723e8e-9e5f-4b16-9fe6-00b13a8fc44c",
  "billingStatus": "SCHEDULED",
  "createdAt": "2026-09-10T14:58:32.573177Z",
  "currencyCode": "USD",
  "cycleNumber": 1,
  "periodEndDate": "2026-10-09",
  "periodStartDate": "2026-09-10",
  "planId": "5dc33cfa-e970-42bd-9962-c231acbaf592",
  "recurringPaymentId": "c8b06947-f299-41b9-92af-04973be05d17",
  "retryCount": 0,
  "scheduledAmount": 3499,
  "scheduledDate": "2026-09-10",
  "taxAmount": 0,
  "totalRefundAmount": 0,
  "updatedAt": "2026-09-10T14:58:32.655582Z"
}

Retrieve a list of billing cycles

Use the following filters to customize your search:

Filters for retrieving a billing cycle
Filter Description
startDate Include cycles whose scheduledDate is on or after this date.
endDate Include cycles whose scheduledDate is on or before this date
pageNumber Zero-based page index. Default 0.
pageSize Records per page. Default 20; valid range 1-100
status Filter by billingStatus field. Allowed values - SCHEDULED, PROCESSING, PAID, FAILED, PAST_DUE, SKIPPED, REFUNDED, PARTIALLY_REFUNDED, ROLLED_OVER, CANCELLED.
sortOrder Defines the direction in which the result set is displayed. Default is scheduledDate, DESC. 
Note

Pagination is available. By default, you use pageNumber 0 and pageSize 20.

HTTP method: GET

Endpoint: /billing-cycles

Scenario: Retrieving list of billing cycles

Response:

Json
{
  "billingCycles": [
    {
      "billingCycleId": "ca3a84bf-9603-48bd-aee4-fe1785d8505f",
      "billingStatus": "SCHEDULED",
      "createdAt": "2026-09-10T15:10:30.946756Z",
      "currencyCode": "USD",
      "cycleNumber": 7,
      "planId": "5dc33cfa-e970-42bd-9962-c231acbaf592",
      "recurringPaymentId": "c8b06947-f299-41b9-92af-04973be05d17",
      "retryCount": 0,
      "scheduledAmount": 2999,
      "scheduledDate": "2027-03-10",
      "totalRefundAmount": 0,
      "updatedAt": "2026-09-10T15:10:30.946756Z"
    },
    {
      "billingCycleId": "342cec58-b814-4bea-b60d-b67b0dfa42b9",
      "billingStatus": "SCHEDULED",
      "createdAt": "2026-09-10T15:08:17.310923Z",
      "currencyCode": "USD",
      "cycleNumber": 6,
      "periodEndDate": "2027-03-09",
      "periodStartDate": "2027-02-10",
      "planId": "5dc33cfa-e970-42bd-9962-c231acbaf592",
      "recurringPaymentId": "c8b06947-f299-41b9-92af-04973be05d17",
      "retryCount": 0,
      "scheduledAmount": 2999,
      "scheduledDate": "2027-02-10",
      "taxAmount": 0,
      "totalRefundAmount": 0,
      "updatedAt": "2026-09-10T15:08:17.310923Z"
    },
    {
      "billingCycleId": "4a9e7e96-0954-4721-a876-1a2d567899ba",
      "billingStatus": "SKIPPED",
      "createdAt": "2026-09-10T14:58:32.722069Z",
      "currencyCode": "USD",
      "cycleNumber": 5,
      "note": "Skipped per customer request",
      "periodEndDate": "2027-02-09",
      "periodStartDate": "2027-01-10",
      "planId": "5dc33cfa-e970-42bd-9962-c231acbaf592",
      "recurringPaymentId": "c8b06947-f299-41b9-92af-04973be05d17",
      "retryCount": 0,
      "scheduledAmount": 2999,
      "scheduledDate": "2027-01-10",
      "statusLastUpdatedAt": "2026-09-10T15:10:30.956056Z",
      "taxAmount": 0,
      "totalRefundAmount": 0,
      "updatedAt": "2026-09-10T15:10:30.956646Z"
    }
  ],
  "pageNumber": 0,
  "pageSize": 20
}

Refund a billing cycle

Preconditions

  • Cycle status must be PAID or PARTIALLY_REFUNDED.
  • Cycle must contain the original transaction ID.
  • The requested amount must not exceed:
    • The cycle amount minus previous refunds, or
    • The remaining prorated refund, when a proration limit exists.

The following fields are required for refunds:

Refund fields
Field Rules
refundAmount Integer greater than zero.
currencyCode Supported ISO currency enum such as USD, EUR, or GBP.
  • Full refund: Refund the entire remaining refundable amount. The cycle becomes REFUNDED.
  • Partial refund: Refund less than the remaining amount. The cycle becomes PARTIALLY_REFUNDED.
  • Additional partial refund: A PARTIALLY_REFUNDED cycle remains eligible for additional refunds while a refundable balance remains. 
  • Prorated cancellation refund: If cancellation established a prorated cap, cumulative refunds cannot exceed that cap.
  • Invoice update: When an invoice exists, the refund amount is applied to it.
  • External payment processing: The service sends a refund request referencing the original payment transaction.

HTTP method: POST

Endpoint: /billing-cycles/{billingCycleId}/refunds

Scenario: Refund part of a successfully paid billing cycle.

Request:

Json
{
  "currencyCode": "USD",
  "refundAmount": 2999
}

Response:

Json
{
  "billingCycleId": "23723e8e-9e5f-4b16-9fe6-00b13a8fc44c",
  "billingStatus": "PARTIALLY_REFUNDED",
  "collectionMethod": "MANUAL",
  "createdAt": "2026-09-10T14:58:32.573177Z",
  "currencyCode": "USD",
  "cycleNumber": 1,
  "note": "Manual retry after payment method update",
  "periodEndDate": "2026-10-09",
  "periodStartDate": "2026-09-10",
  "planId": "5dc33cfa-e970-42bd-9962-c231acbaf592",
  "recurringPaymentId": "c8b06947-f299-41b9-92af-04973be05d17",
  "remainingRefundableAmount": 500,
  "retryCount": 1,
  "scheduledAmount": 3499,
  "scheduledDate": "2026-09-10",
  "statusLastUpdatedAt": "2026-09-10T15:08:16.788378Z",
  "taxAmount": 0,
  "totalPaidAmount": 3499,
  "totalRefundAmount": 2999,
  "transactionDate": "2026-09-10",
  "transactionId": "38f1f374-147f-439c-82c1-f50cebb0ac7a",
  "updatedAt": "2026-09-10T15:08:23.133870Z"
}

Perform a lifecycle action on a billing cycle

You can perform the following lifecycle actions:

Supported action
Action Description Conditions
SKIP Skips the billing cycle without processing a payment.
  • Only a SCHEDULED cycle can be skipped.
  • Changes the current cycle to SKIPPED.
  • Increments the recurring payment’s skip count.
  • Appends an extension cycle after the final scheduled cycle to preserve the total number of billable cycles, if an extension is required.
  • Sets a resume deadline based on the next scheduled cycle.
  • For a single recurring payment, no more than five billing cycles have SKIPPED status at one time.
ROLLOVER Moves the billing cycle to a future date.
  • Only a SCHEDULED cycle can be rolled over.
  • A later SCHEDULED cycle must exist.
  • Adds the current cycle’s scheduled amount to the next cycle.
  • Changes the current cycle to ROLLED_OVER.
RESUME Resumes a previously skipped or modified cycle.
  • scheduledDate is required.
  • The cycle must already be SKIPPED.
RESCHEDULE Reschedules a scheduled cycle.
  • Only a SCHEDULED cycle can be rescheduled.
  • scheduledDate is required.
  • The new date must fall within that cycle’s periodStartDate and periodEndDate.
  • Updates the recurring payment’s next billing date.

HTTP method: POST

Endpoint: /billing-cycles/{billingCycleId}/actions

Scenario: Skip a billing cycle

Request:

Json
{
  "billingCycleAction": "SKIP",
  "note": "Skipped per customer request"
}

Response:

Json
{
  "billingCycleId": "4a9e7e96-0954-4721-a876-1a2d567899ba",
  "billingStatus": "SKIPPED",
  "createdAt": "2026-09-10T14:58:32.722069Z",
  "currencyCode": "USD",
  "cycleNumber": 5,
  "note": "Skipped per customer request",
  "periodEndDate": "2027-02-09",
  "periodStartDate": "2027-01-10",
  "planId": "5dc33cfa-e970-42bd-9962-c231acbaf592",
  "recurringPaymentId": "c8b06947-f299-41b9-92af-04973be05d17",
  "retryCount": 0,
  "scheduledAmount": 2999,
  "scheduledDate": "2027-01-10",
  "statusLastUpdatedAt": "2026-09-10T15:10:30.956056Z",
  "taxAmount": 0,
  "totalRefundAmount": 0,
  "updatedAt": "2026-09-10T15:10:30.956646Z"
}

Collect a past-due billing cycle

The following fields are required for collection.

Collection required fields
Fields Description
recurringPaymentId Recurring-payment unique identifier (UUID).
billingCycleId Billing-cycle UUID.
merchant-id Merchant that owns the billing cycle.
paymentMethod Payment method for the recurring payment.
paymentMethod.consumerProfile Consumer profile and payment method information used for the recurring payment.
currencyCode Specifies the currency using the ISO 4217 code, such as USD, EUR, or GBP.
pastDueAmount Total past-due amount owed for the billing cycle. The pastDueAmount value equals the sum of scheduledAmounts and taxAmount.

HTTP method: POST

Endpoint: /billing-cycles/{billingCycleId}/collections

Scenario: Manually initiate collection for a past-due billing cycle.

Request:

Json
{
  "pastDueAmount": 3499,
  "currencyCode": "USD",
  "note": "Manual retry after payment method update",
  "paymentMethod": {
    "consumerProfile": {
      "consumerProfileId": "{{consumerProfileId}}",
      "paymentMethodId": "{{paymentMethodId}}"
    }
  }
}

Response:

Json
{
  "billingCycleId": "23723e8e-9e5f-4b16-9fe6-00b13a8fc44c",
  "billingStatus": "PAID",
  "collectionMethod": "MANUAL",
  "createdAt": "2026-09-10T14:58:32.573177Z",
  "currencyCode": "USD",
  "cycleNumber": 1,
  "note": "Manual retry after payment method update",
  "paymentStatus": "APPROVED",
  "periodEndDate": "2026-10-09",
  "periodStartDate": "2026-09-10",
  "planId": "5dc33cfa-e970-42bd-9962-c231acbaf592",
  "recurringPaymentId": "c8b06947-f299-41b9-92af-04973be05d17",
  "remainingRefundableAmount": 3499,
  "retryCount": 1,
  "scheduledAmount": 3499,
  "scheduledDate": "2026-09-10",
  "statusLastUpdatedAt": "2026-09-10T15:08:16.788378Z",
  "taxAmount": 0,
  "totalPaidAmount": 3499,
  "totalRefundAmount": 0,
  "transactionDate": "2026-09-10",
  "transactionId": "38f1f374-147f-439c-82c1-f50cebb0ac7a",
  "updatedAt": "2026-09-10T15:08:17.451608Z"
}

Recurring billing cycles

Is this page helpful?