subscription.cancellation

Tracks scheduled subscription cancellations and handles reactivation

Tracks scheduled subscription cancellations.

States: scheduled → notified (optional) → cancelled (terminal/success) → reactivated (terminal/success) → failed (terminal/fail)

All transitions are driven by Stripe webhooks — the workflow does not perform active DB writes. context.session is not required.

Overview

Property	Value
Workflow type	Linear
Library	App-subscription
Version	2.0

Triggers

Source	Endpoint / Event	Description
WEBHOOK	customer.subscription.updated	Stripe webhook when cancel_at is set
WEBHOOK	customer.subscription.deleted	Stripe webhook when subscription is actually cancelled

Input Schema

Field	Type	Required	Default	Description
subscription_uuid	uuid	Yes	—	OrganizationSubscription UUID
organization_uuid	uuid	Yes	—	Organization UUID
stripe_subscription_ref	string	Yes	—	Stripe subscription reference
cancel_at	string	Yes	—	ISO timestamp when subscription will cancel
cancel_at_timestamp	integer	No	—	Unix timestamp when subscription will cancel
trace_ref	string	No	—	Trace reference for request correlation

Output Schema

Field	Type	Required	Default	Description
subscription_uuid	uuid	No	—	—
organization_uuid	uuid	No	—	—
stripe_subscription_ref	string	No	—	—
cancel_at	string	No	—	—
cancel_at_timestamp	integer	No	—	—
trace_ref	string	No	—	—
scheduled_at	string	No	—	—
notified_at	string	No	—	—
cancelled_at	string	No	—	ISO timestamp of the actual Stripe cancellation
completed_at	string	No	—	—
keys_revoked	json	No	—	—
reactivated_at	string	No	—	—
reactivation_reason	string	No	—	—
notification_sent	boolean	No	—	—
notification_sent_at	string	No	—	—
failed_at	string	No	—	—
failure_reason	string	No	—	—
failure_type	string	No	—	—
failed_action	string	No	—	—
failed_at_state	string	No	—	—
failed_step	string	No	—	—
failed_layer	string	No	—	—
error	string	No	—	—
error_type	string	No	—	—

States

State	Initial	Terminal	Success	Auto-advance	Description
scheduled	Yes	No	—	—	Cancellation scheduled, waiting for cancel_at time
notified	No	No	—	—	Pre-cancellation notification sent
cancelled	No	Yes	Yes	—	Subscription cancelled at scheduled time
failed	No	Yes	No	—	Workflow failed
reactivated	No	Yes	Yes	—	User reversed the cancellation

State Diagram

Transitions

From	Action	To	Description
scheduled	send_notification	notified	Send pre-cancellation notification
scheduled	complete_cancellation	cancelled	Complete cancellation from scheduled
notified	complete_cancellation	cancelled	Complete cancellation from notified
scheduled	reactivate	reactivated	User reverses cancellation from scheduled
notified	reactivate	reactivated	User reverses cancellation from notified
* (any state)	fail	failed	Catch-all failure handler

Outcomes

Outcome	Type	Description	State Data Keys
cancelled	SUCCESS	Subscription was cancelled at scheduled time	cancelled_at
reactivated	SUCCESS	User reversed the cancellation	reactivated_at, reactivation_reason
failed	FAILURE	Workflow failed — see failure_reason	failed_at, failure_reason

Alarms

Name	Type	State	Severity	Description
cancellation_failed	state_entered	failed	warning	Subscription cancellation workflow failed

API Usage

# Step 1: Start the workflow
POST /api/workflows/start
Content-Type: application/json

{
  "workflow_type": "subscription.cancellation",
  "initial_data": {
    "subscription_uuid": "value",
    "organization_uuid": "value",
    "stripe_subscription_ref": "value",
    "cancel_at": "value"
  }
}

# Step 2: Webhook triggers transition (customer.subscription.updated)
POST /api/workflows/{workflow_id}/transition
Content-Type: application/json

{ "action": "...", ... webhook payload ... }