Skip to main content

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.

Every request uses your secret key.

How it works​

  1. You create the schedule with its phases, or from a subscription that already exists.
  2. 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.
  3. 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.
  4. When the last phase ends, ONVO applies endBehavior: release leaves the subscription active and billing on its own, and cancel cancels 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​

StatusWhat it means
not_startedThe schedule exists, but its first phase has not started yet.
activatingONVO is creating the subscription for the first phase. It is a passing status.
activeThe schedule has a subscription and moves it through its phases.
completedThe last phase ended and ONVO applied endBehavior.
releasedYou released the schedule. The subscription continues on its own.
canceledYou canceled the schedule.
errorONVO 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 409 with subscription_schedules.version_conflict and nothing is applied. Retrieve the schedule again, check its current state, and retry with the new version.

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:

  • phases replaces the phases that have not started yet. Phases that already started, including the current one, are kept. On a not_started schedule it replaces every phase.
  • endBehavior, defaultCollectionMethod, defaultPaymentMethodId, and defaultDescription change only if you send them.
  • metadata replaces 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 happensThe scheduleThe subscription
You release it with POST /v1/subscription-schedules/{id}/releaseIt 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}/cancelIt 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 endDate or iterations. Do not send both in the same phase.
  • Each phase must start exactly when the previous one ends.
  • iterations accepts values between 1 and 120.
  • Each item carries priceId or priceData, not both. priceData creates 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.
  • quantity accepts values between 1 and 999. If you do not send it, it is 1.
  • trialEnd must fall inside its phase and no more than 365 days after startDate.
  • Payment methods must belong to the schedule's customer.
  • prorationBehavior decides how a period is billed when the phase cuts it short of the price's full interval: none, the default, bills the full interval, and create_prorations bills 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.

CodeWhat it means
subscription_schedules.not_found404. No schedule with that ID exists in the key's account and mode.
subscription_schedules.customer_not_found404. No customer with that ID exists.
subscription_schedules.subscription_not_found404. No subscription exists with the fromSubscription ID.
subscription_schedules.version_conflict409. The schedule changed since you read it. Retrieve it again and retry.
subscription_schedules.from_subscription_exclusiveYou sent fromSubscription together with another parameter.
subscription_schedules.subscription_not_activeThe fromSubscription subscription is not active or trialing.
subscription_schedules.subscription_pending_cancellationThe fromSubscription subscription has a pending cancellation.
subscription_schedules.active_schedule_existsThe subscription already has a schedule in not_started, activating, or active.
subscription_schedules.subscription_has_no_itemsThe subscription has no active items.
subscription_schedules.phases_requiredphases is missing.
subscription_schedules.start_date_mismatchThe schedule's startDate does not match the first phase's.
subscription_schedules.cancel_requires_phase_endendBehavior: "cancel" requires the last phase to have endDate or iterations.
subscription_schedules.phase_requires_endA phase that is not the last has no endDate and no iterations.
subscription_schedules.invalid_phase_datesA phase's endDate is not after its startDate.
subscription_schedules.phases_not_sequentialA phase starts before the previous one ends.
subscription_schedules.phases_not_contiguousA phase does not start exactly when the previous one ends.
subscription_schedules.trial_end_outside_phasetrialEnd falls outside its phase.
subscription_schedules.trial_too_longThe trial period exceeds 365 days.
subscription_schedules.price_not_foundNo price exists with that priceId.
subscription_schedules.product_not_foundNo product exists with the productId in priceData.
subscription_schedules.non_recurring_priceAn item uses a price that is not recurring.
subscription_schedules.mixed_currenciesThe items in a phase use different currencies.
subscription_schedules.mixed_intervalsThe items in a phase use different intervals.
subscription_schedules.mixed_phase_currenciesThe phases use different currencies.
subscription_schedules.invalid_intervalThe price of a phase with iterations has an interval that is not valid.
subscription_schedules.payment_method_not_foundThe payment method does not exist or does not belong to the schedule's customer.
subscription_schedules.invalid_paginationYou sent startingAfter and endingBefore in the same request.
subscription_schedules.invalid_status_for_updateThe schedule is not not_started or active.
subscription_schedules.invalid_status_for_cancelThe schedule is not not_started or active.
subscription_schedules.not_active_for_releaseThe 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 id next to the subscription in your system.
  • Retrieve the schedule before you update it and send its version in expectedVersion.
  • Send Idempotency-Key when you create schedules from processes that retry.
  • Listen for subscription_schedule.transition_failed to detect schedules in error.