Skip to main content
Beta version

Recurring Billing API is in the Beta phase.

Recurring Billing

Recurring payments

Recurring payments manage an ongoing billing agreement between you and the consumer. A recurring payment connects:

  • An active recurring billing plan
  • A consumer profile
  • A stored payment method
  • A billing amount and currency
  • A billing frequency and schedule
  • Optional consumer-specific plan overrides

Refer to the following table for endpoints supported in recurring payments:

Endpoints
Endpoints Business description
POST /recurring/v1/recurring-payments

Creates a recurring payment from an active plan and stored consumer-profile payment method. Supports consumer-specific plan overrides and generates initial billing cycles.
PATCH /recurring/v1/recurring-payments/{recurringPaymentId}

Partially updates fields such as plan, payment method, start/end dates, auto-renewal, tax, name, and plan overrides.
GET /recurring/v1/recurring-payments

Lists your recurring payments. Supports filtering by consumer profile, status, start date, and end date, with pagination.
GET /recurring/v1/recurring-payments/{recurringPaymentId}

Retrieves a single recurring payment by ID.
POST /recurring/v1/recurring-payments/{recurringPaymentId}/actions

Performs PAUSE, RESUME, or CANCEL. Supports immediate and scheduled pause/resume behavior.

Plan overrides

Recurring payments inherit the configuration of their associated plan. When creating or updating a recurring payment, override supported plan settings for that recurring payment, including amount, currency, billing frequency, billing interval, billing day, billing cycle count, auto-renewal, setup fee, trial configuration, and plan type.

Automatic billing calculations

The Recurring Billing service calculates scheduled billing-cycle amounts and dates when you create a recurring payment and when its future schedule is replenished. The amount is inherited from the associated plan unless you provide the planOverrides.amount field. A setup fee is included in the first cycle if applicable, and tax is tracked separately. Billing dates use calendar arithmetic based on the billing frequency.

The following table describes common automatic billing scenarios and explains how recurring charges are processed for each scenario.

Scenarios for automatic billing calculation
Scenario Billing calculation details
If the billing frequency is monthly and the start date of the recurring payment is the 1st of the month. The billing cycle follows the calendar month.
For example: If you set the payment start date to January 1, subsequent billing occurs on February 1, March 1, and so on.
If the billing frequency is monthly and the start date of the recurring payment is any date other than the 1st.

The billing cycle starts on the same date the next month.

For example: If you set the payment start date to March 14, subsequent billing occurs on April 14, May 14, June 14, and so on. The number of days in each billing cycle varies depending on the month.
If the billing frequency is monthly and the start date of the recurring payment is the 30th or 31st of the month

The billing cycle starts on the last day of the month.

For example: If you set the payment start date to the last calendar day of the month, each subsequent billing cycle uses the last calendar date of the month.
If the billing frequency is yearly and the start date of the recurring payment is the 1st of the month

The billing cycle follows the calendar year, including leap years.

For example: If  you set the payment start date to January 1, 2023, subsequent billing occurs on January 1, 2024, January 1, 2025, and so on.
Weekly frequency The next billing date is calculated as the current billing date plus the billingFrequencyCount weeks.
Daily/custom frequency The next billing date is calculated as the current billing date plus the configured number of days.
Full amount billing When the service is consumed for the entire duration of a billing cycle, Recurring Billing determines the full billing amount based on either the plan amount or the payment amount.
Note

The total number of days for each billing cycle varies from 28 to 31, depending on the calendar month for monthly frequency.

Automatic credit calculation

When a recurring payment is canceled, the service checks for a PAID or PARTIALLY_REFUNDED billing cycle contains the cancellation date. If unused days remain, it automatically calculates a prorated refund limit based on the remaining calendar days in that cycle and subtracts any amount already refunded. The calculated amount is stored as proratedAmount on the billing cycle. The recurring payment does not automatically issue a refund. Use the billing-cycle refund endpoint to return funds to the consumer.

The following types of automatic credit calculations and scenarios can occur:

Automatic credit calculation types and scenarios
Automatic credit calculation type Scenario
No credit
  • No PAID or PARTIALLY_REFUNDED billing cycle contains the cancellation date.
  • Cancellation occurs on the final day of the current paid cycle.
Near-full prorated credit
  • Cancellation occurs on the first day of the paid cycle. The cancellation date counts as used. Credit covers all remaining days, not the full cycle.
Prorated credit
  • Cancellation occurs after the first day but before the final day of a paid cycle. Credit is calculated for the unused calendar days remaining in the cycle.
Reduced prorated credit
  • A partial refund was already issued before cancellation. The previously refunded amount is subtracted from the calculated unused-period credit.

Manage recurring payment

Is this page helpful?