Commerce Subscriptions

Commerce Subscriptions

Handle recurring billing plans and customer subscriptions.

How It Works

1. Create subscription plans with pricing, interval (monthly, quarterly, annual), and trial period.
2. Enroll customers by creating a subscription linked to a plan.
3. Track billing cycles and charge dates automatically.
4. Pause, resume, cancel, or skip individual billing cycles.
5. Review billing history, payment status, and subscription events.

Usage

• CLI: stateset-subscriptions ... or stateset "pause subscription sub_123"
• Writes require --apply.
• MCP tools: create_subscription_plan, create_subscription, pause_subscription, resume_subscription, cancel_subscription, skip_billing_cycle, list_billing_cycles.

Permissions

• Read: list_billing_cycles — no --apply needed.
• Write: create_subscription_plan, create_subscription, pause_subscription, resume_subscription, cancel_subscription, skip_billing_cycle — requires --apply.

Examples

stateset subscriptions create-plan --name "Pro Monthly" --interval monthly --price 29.99 --apply
stateset subscriptions create --customer cust_123 --plan plan_456 --apply
stateset subscriptions pause sub_123 --apply
stateset subscriptions cancel sub_123 --at-period-end --apply

Status Flows

Subscription: Active -> Paused -> Active (or Cancelled/Expired)

Billing Cycle: Scheduled -> Charged -> Paid (or Failed/Skipped)

Output

{"status":"active","subscription_id":"sub_123","plan":"monthly","next_charge_date":"2025-02-01","amount":29.99}

Present Results to User

• Plan and subscription identifiers with current status.
• Billing interval, next charge date, and recurring amount.
• Any proration, trial period, or cancellation effective date.
• Payment history for recent billing cycles.

Troubleshooting

• Plan archived: select an active plan; archived plans cannot accept new enrollments.
• Past due: review billing cycles, retry failed payment, or update payment method.
• Cancel timing: confirm whether cancellation is immediate or at end of billing period.
• Duplicate subscription: check if customer already has an active subscription to the same plan.

Error Codes

• PLAN_ARCHIVED: Archived plans cannot accept new enrollments.
• BILLING_PAST_DUE: Payment failed for the current billing cycle.
• DUPLICATE_SUBSCRIPTION: Customer already has an active subscription to this plan.

Related Skills

• commerce-payments — payment processing for subscription charges
• commerce-customers — customer records linked to subscriptions
• commerce-invoices — invoices generated per billing cycle

References

• references/subscriptions-flow.md
• /home/dom/stateset-icommerce/cli/.claude/agents/subscriptions.md