Scheduled changes allow you to queue modifications to subscriptions, plans, or other entities that take effect at a future date. Common uses include price increases, plan migrations, and feature launches.
Key concepts:
- Release strategy -
immediate(execute now),scheduled(at a specific datetime), ornext_period(at the start of the next billing cycle) - Dependencies - chain changes so one executes only after another completes
- Rollback window - how long after execution the change can be reversed
- Notification - optionally notify the customer before a change takes effect
List scheduled changes
Lists scheduled changes with optional filters and cursor-based pagination
query Parameters
limitNumber of items per page
cursorPagination cursor
statusFilter by status
entity_typeFilter by entity type
entity_idFilter by entity UUID
List scheduled changes › Responses
Paginated list wrapped in data envelope
change_payloadchange_typecreated_atcreated_bydepends_on_change_identity_identity_typeentity_version_at_scheduleidnotification_configorganization_idprevious_staterelease_strategyreleased_atrollback_windowrolled_back_atscheduled_atstatusupdated_atCreate a scheduled change
Schedules a new change, returning any conflicts with existing scheduled changes
Create a scheduled change › Request Body
change_payloadchange_typecreated_bydepends_on_change_identity_identity_typeentity_version_at_scheduleimmediatenotification_configrelease_strategyrollback_windowscheduled_atCreate a scheduled change › Responses
Wrapped in data envelope (may include conflicts)
change_payloadchange_typecreated_atcreated_bydepends_on_change_identity_identity_typeentity_version_at_scheduleidnotification_configorganization_idprevious_staterelease_strategyreleased_atrollback_windowrolled_back_atscheduled_atstatusupdated_atCancel a batch of pending/upcoming scheduled changes
Cancels each change in the request atomically and reports
per-row outcome: cancelled[] for the IDs that transitioned
to cancelled, skipped[] for those that couldn't (invalid
UUID, not found, already released/rolled-back, etc.). The
endpoint never fails the whole batch — invalid rows are
surfaced individually so the UI can show "5 of 7 cancelled".
Cancel a batch of pending/upcoming scheduled changes › Responses
Wrapped in data envelope
cancelledGet a scheduled change
Retrieves a scheduled change by ID
path Parameters
idScheduled change UUID
Get a scheduled change › Responses
Wrapped in data envelope
change_payloadchange_typecreated_atcreated_bydepends_on_change_identity_identity_typeentity_version_at_scheduleidnotification_configorganization_idprevious_staterelease_strategyreleased_atrollback_windowrolled_back_atscheduled_atstatusupdated_atUpdate a scheduled change
Updates a pending scheduled change by ID
path Parameters
idScheduled change UUID
Update a scheduled change › Request Body
change_payloadnotification_configrelease_strategyrollback_windowscheduled_atUpdate a scheduled change › Responses
Wrapped in data envelope
change_payloadchange_typecreated_atcreated_bydepends_on_change_identity_identity_typeentity_version_at_scheduleidnotification_configorganization_idprevious_staterelease_strategyreleased_atrollback_windowrolled_back_atscheduled_atstatusupdated_atDiff a scheduled change against the entity's current state
Returns {entity_type, entity_id, before, after, changed_fields}
where before is the entity's current live state and after
is before merged with the scheduled change's change_payload.
The centralized scheduled-changes page (workstream 14) uses
this to render a side-by-side preview of the pending change.
path Parameters
idScheduled change UUID
Diff a scheduled change against the entity's current state › Responses
Wrapped in data envelope
afterbeforechanged_fieldsentity_identity_typeReconfirm a stale scheduled change
Transitions a stale change back to pending, acknowledging that the upstream entity mutation does not invalidate the scheduled payload. To amend the payload, follow reconfirm with PUT.
path Parameters
idScheduled change UUID
Reconfirm a stale scheduled change › Responses
Wrapped in data envelope
change_payloadchange_typecreated_atcreated_bydepends_on_change_identity_identity_typeentity_version_at_scheduleidnotification_configorganization_idprevious_staterelease_strategyreleased_atrollback_windowrolled_back_atscheduled_atstatusupdated_atRelease a scheduled change
Applies a pending scheduled change immediately
path Parameters
idScheduled change UUID
Release a scheduled change › Responses
Wrapped in data envelope
change_payloadchange_typecreated_atcreated_bydepends_on_change_identity_identity_typeentity_version_at_scheduleidnotification_configorganization_idprevious_staterelease_strategyreleased_atrollback_windowrolled_back_atscheduled_atstatusupdated_atReschedule a pending/upcoming scheduled change
Moves the scheduled_at of a PENDING or UPCOMING change to a new future timestamp. Re-runs the existing FindConflicts check (same predicate as Create). The release hook applies the change_payload at release time and stamps the new version row's effective_from from ScheduledAt (see scheduler/hooks.go::EffectiveFromSetter), so updating scheduled_changes.scheduled_at is sufficient — there is no pre-existing SCHEDULED version row coupled to this scheduled_change in the standard flow.
path Parameters
idScheduled change UUID
Reschedule a pending/upcoming scheduled change › Responses
Wrapped in data envelope
change_payloadchange_typecreated_atcreated_bydepends_on_change_identity_identity_typeentity_version_at_scheduleidnotification_configorganization_idprevious_staterelease_strategyreleased_atrollback_windowrolled_back_atscheduled_atstatusupdated_atRollback a scheduled change
Rolls back a previously released scheduled change
path Parameters
idScheduled change UUID
Rollback a scheduled change › Responses
Wrapped in data envelope
change_payloadchange_typecreated_atcreated_bydepends_on_change_identity_identity_typeentity_version_at_scheduleidnotification_configorganization_idprevious_staterelease_strategyreleased_atrollback_windowrolled_back_atscheduled_atstatusupdated_at