API ReferenceSubscriptions

Get Next Action

View as Markdown
Get next action for subscription lifecycle. Central decision point for Restate workflow. Evaluates: 1. Terminal states (CANCELLED, PAUSED) → stop 2. Invoice issues (UNCOLLECTIBLE, PAST_DUE) → cancel or dunning 3. Subscription flags (cancel_at_period_end) → cancel or stop 4. State-based scheduling → schedule next action Returns action for workflow to execute: - action: "stop", "cancel", "schedule_billing", "schedule_activation", "schedule_dunning", "process_past_due" - reason: Explanation if action is "stop" or "cancel" - at: ISO timestamp for scheduled actions - invoice_id: Invoice ID for invoice-specific actions For simulation subscriptions, effects are executed immediately to drive state transitions.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

subscription_idstringRequired
account_idstringRequired

Headers

X-Restate-Secret-Keystring or nullOptional
X-System-Reasonstring or nullOptional

Response

Successful Response
actionenum

Actions returned by get_next_action for subscription lifecycle management.

Terminal actions:

  • STOP: End the lifecycle loop (subscription is cancelled, paused, or complete)
  • CANCEL: Cancel the subscription, then stop

Scheduling actions:

  • SCHEDULE_BILLING: Wait until specified time, then create renewal invoice
  • SCHEDULE_ACTIVATION: Wait until specified time, then activate subscription
  • SCHEDULE_COLLECTION: Wait until specified time, then attempt payment collection
  • SCHEDULE_RESUME: Wait until specified time, then resume paused subscription
  • APPLY_SCHEDULED_PAUSE: Wait until period end, then apply scheduled pause (pause_at_end)
  • NOTIFY_TRIAL_ENDING: Wait until specified time, then emit trial_will_end event

Immediate actions:

  • PROCESS_PAST_DUE: Immediately process a past-due invoice
  • APPLY_DUNNING_END_BEHAVIOR: Apply configured dunning end behavior (cancel/keep + invoice handling)
  • RENEW_CONTRACT: Reset billing cycles and continue (contract_auto_renew=true)
  • EXECUTE_PENDING_CHANGE: Execute a pending plan change scheduled for period end
reasonstring or nullOptional
atdatetime or nullOptional
invoice_idstring or nullOptional
dunning_behaviorstring or nullOptional

Errors

422
Unprocessable Entity Error