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. Two shapes share this path: the legacy cursor shape (cursor + has_more, apifilter grammar) and the centralized page's filtered shape (offset pagination, comma-separated multi-select filters, [from,to] window, sort) which activates when any of scheduled_at_from/scheduled_at_to/group_by/offset/sort - or limit without cursor - is present.
query Parameters
limitPage size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.
cursorOpaque continuation token from the previous response's pagination.cursor. Omit for the first page. Cursors are stateless and do not expire, but are only valid for the list and filters that produced them.
offsetPage offset (filtered shape)
Page offset (filtered shape)
sortscheduled_at|created_at with optional :asc/:desc suffix (filtered shape)
scheduled_at|created_at with optional :asc/:desc suffix (filtered shape)
group_byPresence flips to the filtered shape
Presence flips to the filtered shape
statusFilter by status (comma-separated in the filtered shape; apifilter ops in the legacy shape)
Filter by status (comma-separated in the filtered shape; apifilter ops in the legacy shape)
entity_typeFilter by entity type
Filter by entity type
entity_idFilter by entity UUID
Filter by entity UUID
change_typeFilter by change type
Filter by change type
product_idLegacy shape: filter by product UUID
Legacy shape: filter by product UUID
scheduled_at_fromRFC3339 lower bound (filtered shape)
RFC3339 lower bound (filtered shape)
scheduled_at_toRFC3339 upper bound (filtered shape)
RFC3339 upper bound (filtered shape)
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
List scheduled changes › Responses
OK
Create a scheduled change
Schedules a new change. When other pending/upcoming changes target the same entity, the response additionally carries them in conflicts.
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Create a scheduled change › Request Body
change_payloadEntity-type-specific change body applied by the release hook at fire time; validated only for non-emptiness at authoring.
change_typeDiscriminator routing the release hook (e.g. UPDATE, version_bump); the payload shape is interpreted per this value only at fire time.
created_byUser who scheduled the change.
depends_on_change_idOptional predecessor change that must be released before this one.
entity_idId of the entity the change targets.
entity_typeKind of entity the change targets (PROMOTION/PLAN/SUBSCRIPTION/PRODUCT).
entity_version_at_scheduleThe entity version observed when scheduling; a mismatch at release is logged as a staleness warning.
immediateRelease now instead of at scheduled_at (skips the future-date check).
Free-form metadata map carried on the change.
notification_configOptional notification configuration carried alongside the change.
release_strategyAUTOMATIC (the ticker releases at scheduled_at) or MANUAL; defaults to AUTOMATIC.
rollback_windowOptional Postgres interval string bounding how long after release the change may be rolled back.
scheduled_atWhen the change should be released; must be in the future unless immediate is set.
Create a scheduled change › Responses
Created
Cancel a batch of pending/upcoming scheduled changes
Cancels each change in the request 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".
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Cancel a batch of pending/upcoming scheduled changes › Responses
OK
Get a scheduled change
path Parameters
idScheduled change UUID
Scheduled change UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Get a scheduled change › Responses
OK
Update a scheduled change
Updates a pending scheduled change.
path Parameters
idScheduled change UUID
Scheduled change UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Update a scheduled change › Request Body
change_payloadReplacement change body applied by the release hook at fire time; validated only for non-emptiness at authoring.
Replacement free-form metadata map.
notification_configReplacement notification configuration.
release_strategyNew release strategy: AUTOMATIC or MANUAL.
rollback_windowReplacement Postgres interval string bounding the post-release rollback window.
scheduled_atNew release time; must be in the future.
Update a scheduled change › Responses
OK
Delete a scheduled change
Cancels a pending or upcoming scheduled change.
path Parameters
idScheduled change UUID
Scheduled change UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Delete a scheduled change › Responses
No Content
Diff 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 uses this to render a side-by-side preview of the pending change.
path Parameters
idScheduled change UUID
Scheduled change UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Diff a scheduled change against the entity's current state › Responses
OK
Reconfirm 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
Scheduled change UUID
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Reconfirm a stale scheduled change › Responses
OK
Release a scheduled change
Applies a pending scheduled change immediately.
path Parameters
idScheduled change UUID
Scheduled change UUID
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Release a scheduled change › Responses
OK
Reschedule a pending/upcoming scheduled change
Moves the scheduled_at of a PENDING or UPCOMING change to a new future timestamp. Re-runs the same conflict check as create; the release hook stamps the new version row's effective_from from scheduled_at.
path Parameters
idScheduled change UUID
Scheduled change UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Reschedule a pending/upcoming scheduled change › Responses
OK
Rollback a scheduled change
Rolls back a previously released scheduled change.
path Parameters
idScheduled change UUID
Scheduled change UUID
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Rollback a scheduled change › Responses
OK