subscription.renewal

Tracks and handles subscription renewals

Tracks subscription renewals.

States: upcoming → notified (optional) → processing → renewed (terminal/success) → payment_failed (terminal/fail) → failed (terminal/fail)

Key features: - Tracks upcoming renewals from invoice.upcoming webhook - Optional renewal reminder notifications - Handles payment success and failure outcomes

Overview

Property	Value
Workflow type	Linear
Library	App-subscription
Version	2.0

Triggers

Source	Endpoint / Event	Description
WEBHOOK	invoice.upcoming	Stripe webhook for upcoming invoice — starts the workflow
WEBHOOK	invoice.paid	Stripe webhook when payment succeeds — call action='payment_succeeded'
WEBHOOK	invoice.payment_failed	Stripe webhook when payment fails — call action='payment_failed'

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
stripe_invoice_ref	string	Yes	—	Stripe invoice reference
stripe_customer_ref	string	No	—	Stripe customer reference
amount_due	integer	Yes	—	Amount due in cents
currency	string	No	—	Currency code (default: usd)
due_date	string	Yes	—	Due date ISO timestamp

Output Schema

Field	Type	Required	Default	Description
subscription_uuid	uuid	No	—	—
organization_uuid	uuid	No	—	—
stripe_subscription_ref	string	No	—	—
stripe_invoice_ref	string	No	—	—
stripe_customer_ref	string	No	—	—
amount_due	integer	No	—	—
currency	string	No	—	—
due_date	string	No	—	—
detected_at	string	No	—	—
notified_at	string	No	—	—
processing_started_at	string	No	—	—
payment_processing_started_at	string	No	—	—
notification_sent	boolean	No	—	—
notification_sent_at	string	No	—	—
paid_at	string	No	—	—
renewed_at	string	No	—	ISO timestamp when renewal succeeded
amount_paid	integer	No	—	Amount actually paid in minor units
payment_intent_ref	string	No	—	—
keys_expiry_bumped	json	No	—	—
payment_failed_at	string	No	—	—
failure_reason	string	No	—	—
failure_code	string	No	—	—
next_retry_at	string	No	—	—
failed_at	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
upcoming	Yes	No	—	—	Renewal approaching, invoice created
notified	No	No	—	—	Renewal reminder sent to customer
processing	No	No	—	—	Payment is being processed by Stripe
failed	No	Yes	No	—	Workflow failed
payment_failed	No	Yes	No	—	Renewal payment failed
renewed	No	Yes	Yes	—	Subscription renewed successfully

State Diagram

Transitions

From	Action	To	Description
upcoming	send_notification	notified	Send renewal reminder
upcoming	payment_processing	processing	Payment started from upcoming
notified	payment_processing	processing	Payment started from notified
processing	payment_succeeded	renewed	Payment succeeded
upcoming	payment_succeeded	renewed	Quick renewal from upcoming
notified	payment_succeeded	renewed	Renewal from notified
processing	payment_failed	payment_failed	Payment failed from processing
upcoming	payment_failed	payment_failed	Payment failed from upcoming
notified	payment_failed	payment_failed	Payment failed from notified
* (any state)	fail	failed	Catch-all failure handler

Outcomes

Outcome	Type	Description	State Data Keys
renewed	SUCCESS	Subscription renewed successfully	renewed_at, amount_paid
payment_failed	FAILURE	Renewal payment failed (may trigger recovery workflow)	payment_failed_at, failure_reason, failure_code
failed	FAILURE	Workflow error — see failure_reason	failed_at, failure_reason

Alarms

Name	Type	State	Severity	Description
renewal_payment_failed	state_entered	payment_failed	warning	Subscription renewal payment failed

API Usage

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

{
  "workflow_type": "subscription.renewal",
  "initial_data": {
    "subscription_uuid": "value",
    "organization_uuid": "value",
    "stripe_subscription_ref": "value",
    "stripe_invoice_ref": "value"
  }
}

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

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