---
api: 'Merchant API'
---

# 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_date` pushes this entire sequence—the end of Cycle 1, the start of Cycle 2, and the delayed billing trigger—further into the future.

Subsequent cycles resume the original plan cadence (e.g., monthly) from the new date.

## Endpoint

POST `/api/subscriptions/{subscription_id}/change-renewal-date`

## Request body

### Attributes

- `renewal_date` (string)
    The new renewal date for the subscription, expressed as a UTC date-time value.
    
    Must be set to a date later than the current renewal date; earlier dates are rejected.

## Returns

### 204

Renewal date updated successfully

## Error responses

| HTTP status code | Description |
| --- | --- |
| 400 | Bad Request |
| 401 | Unauthorized |
| 404 | Subscription not found |
| 422 | Unprocessable entity (business rule violation) |