Update a subscription renewal date
Reschedule the upcoming payment date for an active subscription cycle. This is a command endpoint — the renewal date is not a direct field on the Subscription resource, but is derived from the current active cycle's end_date.
Use cases
- Payment extensions: Granting a customer more time to pay.
- Service delays: Adjusting the billing date if service delivery is delayed.
- Billing alignment: Moving a payment date to better suit a customer's financial schedule.
How it works
Extending the current cycle's end_date naturally postpones the start of the next cycle and its associated payment trigger, providing flexibility for both the merchant and the customer.
The relationship between the cycle end and the billing execution depends on the plan type:
- Non-usage plans: The next cycle's start date is the same as the billing date. The moment the current cycle ends, the next cycle begins and the payment is attempted.
- Usage-based plans (buffer & overlap): To allow merchants time to finalize usage data, the billing date is scheduled after the cycle
end_date.- Usage continues to be aggregated until the updated
end_date. - When the current cycle (Cycle 1) reaches its updated
end_date, Cycle 2 starts immediately to ensure no service interruption. - The billing for Cycle 1 occurs a few hours later (12-hour buffer). This window allows you to upload or edit usages for the period that just ended while the customer is already technically in their next cycle.
- Rescheduling the
renewal_datepushes this entire sequence—the end of Cycle 1, the start of Cycle 2, and the delayed billing trigger—further into the future.
- Usage continues to be aggregated until the updated
Subsequent cycles resume the original plan cadence (e.g., monthly) from the new date.
Request
Response
Renewal date updated successfully