Subscription schedules
A schedule defines in advance how a subscription changes over time. It is made of phases: each phase has a start date and the prices and quantities it bills, and it can have an end date, a trial period, and its own payment method. ONVO starts each phase on its date and applies its items to the subscription.
Use it, for example, to bill a launch price for three months and then the regular price, to set up a plan change that applies when the current period ends, or to sell a plan with a fixed number of charges.
Related API reference
- Create a schedule
- List schedules
- Count schedules
- Retrieve a schedule
- Update a schedule
- Cancel a schedule
- Release a schedule
- Webhook events
Every request uses your secret key.
How it works
- You create the schedule with its phases, or from a subscription that already exists.
- When the first phase starts, ONVO creates the subscription with that phase's items and stores its identifier in
subscriptionId. A schedule created from an existing subscription has it from the start. - When each later phase starts, ONVO replaces the subscription's items with the phase's items and creates the invoice for that phase's first period.
- When the last phase ends, ONVO applies
endBehavior:releaseleaves the subscription active and billing on its own, andcancelcancels it.
ONVO starts phases in a check that runs every three hours, so a phase can start up to about three hours after its startDate. Billing periods are counted from the phase's startDate, not from the time of the check.
Phases are numbered from 0. lastTransitionedPhaseIndex shows the current phase and is -1 until one has started.
Statuses
| Status | What it means |
|---|---|
not_started | The schedule exists, but its first phase has not started yet. |
activating | ONVO is creating the subscription for the first phase. It is a passing status. |
active | The schedule has a subscription and moves it through its phases. |
completed | The last phase ended and ONVO applied endBehavior. |
released | You released the schedule. The subscription continues on its own. |
canceled | You canceled the schedule. |
error | ONVO could not start a phase after five attempts. |
You can only update, cancel, or release a schedule in not_started or active.
Create a schedule with phases
Send customerId and phases. This example bills a launch price for three periods and then the regular price, with no end date:
curl https://api.onvopay.com/v1/subscription-schedules \
-X POST \
-H "Authorization: Bearer $ONVO_SECRET_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $UNIQUE_KEY" \
-d '{
"customerId": "$CUSTOMER_ID",
"defaultPaymentMethodId": "$PAYMENT_METHOD_ID",
"defaultDescription": "Pro Plan",
"endBehavior": "release",
"phases": [
{
"startDate": "2027-01-01T00:00:00.000Z",
"iterations": 3,
"items": [
{ "priceId": "$LAUNCH_PRICE_ID", "quantity": 1 }
]
},
{
"startDate": "2027-04-01T00:00:00.000Z",
"items": [
{ "priceId": "$REGULAR_PRICE_ID", "quantity": 1 }
]
}
]
}'
The schedule starts as not_started, with version set to 0 and subscriptionId set to null. When the first phase's startDate arrives, ONVO creates the subscription, moves the schedule to active, and sends subscription_schedule.activated. If that startDate has already passed when you create the schedule, ONVO activates it without waiting for the next check.
Send one of the customer's payment methods in defaultPaymentMethodId or in the first phase's paymentMethodId. Without a payment method the schedule cannot activate and, after five attempts, it ends up in error.
With iterations, ONVO calculates the phase's endDate from the interval of its first item's price. In the example, three periods of a monthly price starting on January 1 end on April 1, which is exactly when the next phase must start.
Create a schedule from an existing subscription
Send only fromSubscription, with no other parameter:
curl https://api.onvopay.com/v1/subscription-schedules \
-X POST \
-H "Authorization: Bearer $ONVO_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"fromSubscription": "$SUBSCRIPTION_ID"
}'
The subscription must be active or trialing, have at least one active item, have no pending cancellation, and have no other schedule in not_started, activating, or active.
The schedule starts as active, with endBehavior set to release and a single phase that covers the subscription's current period with its current items. It takes the collection method, payment method, description, and metadata from the subscription. Because it starts active, it sends subscription_schedule.created and not subscription_schedule.activated.
Then add the phases that follow with an update. The first new phase must start exactly at the current phase's endDate:
curl https://api.onvopay.com/v1/subscription-schedules/$SCHEDULE_ID \
-X POST \
-H "Authorization: Bearer $ONVO_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"expectedVersion": 0,
"phases": [
{
"startDate": "$CURRENT_PHASE_END_DATE",
"items": [
{ "priceId": "$NEW_PRICE_ID", "quantity": 1 }
]
}
]
}'
Update a schedule
Each schedule has a version that starts at 0 and increases by one with each update and each phase change. When you update, send the version you read in expectedVersion:
- If it matches, ONVO applies the change and increases
version. - If the schedule changed since you read it, the response is
409withsubscription_schedules.version_conflictand nothing is applied. Retrieve the schedule again, check its current state, and retry with the newversion.
This way two simultaneous requests, or a phase change that happens while you edit, do not overwrite each other. Because a phase change also increases version, retrieve the schedule right before you update it.
What you can change:
phasesreplaces the phases that have not started yet. Phases that already started, including the current one, are kept. On anot_startedschedule it replaces every phase.endBehavior,defaultCollectionMethod,defaultPaymentMethodId, anddefaultDescriptionchange only if you send them.metadatareplaces all the previous metadata.
If the schedule already has a subscription, changes to defaultDescription, defaultCollectionMethod, defaultPaymentMethodId, and metadata also apply to that subscription.
Release or cancel
| What happens | The schedule | The subscription |
|---|---|---|
You release it with POST /v1/subscription-schedules/{id}/release | It becomes released with subscriptionId set to null. | It stays active and bills its current items on its own. |
You cancel it with POST /v1/subscription-schedules/{id}/cancel | It becomes canceled. | If the schedule was active, it is canceled and its invoices in open status are voided. |
The last phase ends with endBehavior: "release" | It becomes completed with subscriptionId set to null. | It stays active and bills the last phase's items on its own. |
The last phase ends with endBehavior: "cancel" | It becomes completed and keeps subscriptionId. | It is canceled and its invoices in open status are voided. |
Releasing or canceling a not_started schedule ends it without creating a subscription.
If the last phase has no endDate and no iterations, the schedule stays active until you release or cancel it. That is why endBehavior: "cancel" requires, when you create the schedule, that the last phase has endDate or iterations.
Phase rules
- Send between 1 and 10 phases per request, and between 1 and 10 items per phase.
- Every phase except the last must have
endDateoriterations. Do not send both in the same phase. - Each phase must start exactly when the previous one ends.
iterationsaccepts values between 1 and 120.- Each item carries
priceIdorpriceData, not both.priceDatacreates a new recurring price for an existing product. - Prices must be recurring. The items in a phase must share currency and interval, and all phases must use the same currency.
quantityaccepts values between 1 and 999. If you do not send it, it is 1.trialEndmust fall inside its phase and no more than 365 days afterstartDate.- Payment methods must belong to the schedule's customer.
prorationBehaviordecides how a period is billed when the phase cuts it short of the price's full interval:none, the default, bills the full interval, andcreate_prorationsbills the proportional part.
Retry creation without duplicating
Send the Idempotency-Key header with a unique value when you create a schedule. If you repeat the request with the same key, ONVO returns the first response instead of creating another schedule. ONVO keeps each key for at least 24 hours.
While the first request is still in progress, a repeat with the same key responds 409. If the first request failed, you can retry with the same key.
Errors
Schedule API errors use subscription_schedules.* codes. They respond 400, except where noted.
A body that does not have the expected format also responds 400, but with no code: message carries the list of validation messages. It happens, for example, with a parameter the API does not recognize, with more than 10 phases, with endDate and iterations in the same phase, or with an item that carries both priceId and priceData or neither.
| Code | What it means |
|---|---|
subscription_schedules.not_found | 404. No schedule with that ID exists in the key's account and mode. |
subscription_schedules.customer_not_found | 404. No customer with that ID exists. |
subscription_schedules.subscription_not_found | 404. No subscription exists with the fromSubscription ID. |
subscription_schedules.version_conflict | 409. The schedule changed since you read it. Retrieve it again and retry. |
subscription_schedules.from_subscription_exclusive | You sent fromSubscription together with another parameter. |
subscription_schedules.subscription_not_active | The fromSubscription subscription is not active or trialing. |
subscription_schedules.subscription_pending_cancellation | The fromSubscription subscription has a pending cancellation. |
subscription_schedules.active_schedule_exists | The subscription already has a schedule in not_started, activating, or active. |
subscription_schedules.subscription_has_no_items | The subscription has no active items. |
subscription_schedules.phases_required | phases is missing. |
subscription_schedules.start_date_mismatch | The schedule's startDate does not match the first phase's. |
subscription_schedules.cancel_requires_phase_end | endBehavior: "cancel" requires the last phase to have endDate or iterations. |
subscription_schedules.phase_requires_end | A phase that is not the last has no endDate and no iterations. |
subscription_schedules.invalid_phase_dates | A phase's endDate is not after its startDate. |
subscription_schedules.phases_not_sequential | A phase starts before the previous one ends. |
subscription_schedules.phases_not_contiguous | A phase does not start exactly when the previous one ends. |
subscription_schedules.trial_end_outside_phase | trialEnd falls outside its phase. |
subscription_schedules.trial_too_long | The trial period exceeds 365 days. |
subscription_schedules.price_not_found | No price exists with that priceId. |
subscription_schedules.product_not_found | No product exists with the productId in priceData. |
subscription_schedules.non_recurring_price | An item uses a price that is not recurring. |
subscription_schedules.mixed_currencies | The items in a phase use different currencies. |
subscription_schedules.mixed_intervals | The items in a phase use different intervals. |
subscription_schedules.mixed_phase_currencies | The phases use different currencies. |
subscription_schedules.invalid_interval | The price of a phase with iterations has an interval that is not valid. |
subscription_schedules.payment_method_not_found | The payment method does not exist or does not belong to the schedule's customer. |
subscription_schedules.invalid_pagination | You sent startingAfter and endingBefore in the same request. |
subscription_schedules.invalid_status_for_update | The schedule is not not_started or active. |
subscription_schedules.invalid_status_for_cancel | The schedule is not not_started or active. |
subscription_schedules.not_active_for_release | The schedule is not not_started or active. |
When a schedule ends up in error
If ONVO cannot activate the schedule or start a phase, it retries. After five failed attempts the schedule moves to error and ONVO sends subscription_schedule.transition_failed. transitionAttempts counts the failed attempts.
A schedule in error cannot be updated, canceled, or released through the API.
Webhooks
ONVO sends a subscription_schedule.* event when a schedule is created, updated, activated, changes phase, completes, is released, is canceled, or fails. See the list and the fields in Webhook events.
Best practices
- Store the schedule
idnext to the subscription in your system. - Retrieve the schedule before you update it and send its
versioninexpectedVersion. - Send
Idempotency-Keywhen you create schedules from processes that retry. - Listen for
subscription_schedule.transition_failedto detect schedules inerror.