subscription.plan.change-with-proration

Change a subscription plan, preview proration, collect confirmation when required, and reconcile entitlements.

Change a subscription plan, preview proration, collect confirmation when required, and reconcile entitlements.

Overview

Property	Value
Workflow type	Dag
Library	App-subscription
Version	1.0

Input Schema

Field	Type	Required	Default	Description
workflow_run_id	string	No	—	DAG-stamped parent run id.
organization_uuid	uuid	Yes	—	Organization UUID for tenant isolation.
actor	string	No	—	User or service actor initiating the workflow.
idempotency_key	string	No	—	Caller-supplied idempotency key for safe retries.
dry_run	boolean	No	—	Validate and plan without mutating external resources.
subscription_uuid	uuid	Yes	—	Subscription UUID.
target_plan	string	Yes	—	Target plan key.
billing_cycle	string	No	—	Billing cycle.
confirm	boolean	No	—	Apply after preview/approval.
effective_at	string	No	—	Effective timestamp.

Output Schema

Field	Type	Required	Default	Description
organization_uuid	uuid	No	—	Organization uuid.
workflow_run_uuid	uuid	No	—	Workflow run uuid.
status	string	No	—	Status.
summary	json	No	—	Summary.
resource_refs	json	No	—	Resource refs.
warnings	list	No	—	Warnings.
completed_at	string	No	—	Completed at.
compensation_trigger	string	No	—	Compensation trigger.
compensation_results	json	No	—	Compensation results.
data_subscription_list	json	No	—	Output state_data from DAG step data_subscription_list.
data_subscription_plan_list	json	No	—	Output state_data from DAG step data_subscription_plan_list.
subscription_plan_change	json	No	—	Output state_data from DAG step subscription_plan_change.
approval_request_collect_and_expire	json	No	—	Output state_data from DAG step approval_request_collect_and_expire.
failure_reason	string	No	—	Failure reason.
failed_step	json	No	—	Failed step.
failed_layer	json	No	—	Failed layer.
failed_at_state	string	No	—	Failed at state.
error	string	No	—	Error.
error_type	string	No	—	Error type.
failed_at	string	No	—	Failed at.

DAG Layers

#	Layer	Steps	Compensation
1	01_data_subscription_list	data.subscription.list	—
2	02_data_subscription_plan_list	data.subscription.plan.list	—
3	03_subscription_plan_change	subscription.plan_change	—
4	04_approval_request_collect_and_expire	approval.request.collect-and-expire	—

Execution Flow

Sub-workflows

Sub-workflow	Step name
data.subscription.list	data_subscription_list
data.subscription.plan.list	data_subscription_plan_list
subscription.plan_change	subscription_plan_change
approval.request.collect-and-expire	approval_request_collect_and_expire

API Usage

POST /api/workflows/start
Content-Type: application/json

{
  "workflow_type": "subscription.plan.change-with-proration",
  "initial_data": {
    "organization_uuid": "value",
    "subscription_uuid": "value",
    "target_plan": "value"
  }
}