billing-state-machine

Define and enforce billing state transitions for SaaS subscriptions.

Updated Mar 29, 2026

Search Tags:#subscriptions #concurrency #billing #stripe #webhooks #state-machine #audit-logs

Ready to run

npx skills add https://github.com/marquesfelip/agents-and-skills --skill billing-state-machine

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: billing-state-machine
Source: https://github.com/marquesfelip/agents-and-skills/tree/main/skills/billing-state-machine
Command: npx skills add https://github.com/marquesfelip/agents-and-skills --skill billing-state-machine

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Billing state machine solves the challenge of defining, enforcing, and synchronizing subscription states across systems, ensuring consistent access control and accurate Stripe status.

Core Features & Use Cases

Define all valid states and their allowed transitions and provide a single source of truth for state changes.
Enforce transitions at the database and application layer, preventing invalid state changes and race conditions.
Synchronize Stripe subscription statuses to local state using a deterministic mapping from Stripe events to transitions.
Handle concurrent webhook events safely with optimistic locking and idempotent transitions.
Emit downstream effects (entitlements, emails, audit logs) on each transition to keep downstream systems in sync.

Quick Start

Implement the state machine in your subscription service and wire Stripe webhooks to drive transitions.

Frequently Asked Questions about billing-state-machine

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I handle concurrent Stripe webhooks to prevent race conditions in subscription billing?▼

Concurrent Stripe webhooks are handled safely using optimistic locking and idempotent transition guards to prevent race conditions in subscription billing. This ensures that duplicate or out-of-order events do not corrupt your local state.

What is a billing state machine and when do I need one for SaaS subscriptions?▼

A billing state machine defines valid states and enforces allowed transitions for SaaS subscriptions. You need one to maintain a single source of truth, prevent invalid state changes, and synchronize local access control with Stripe.

How do I synchronize Stripe subscription statuses to my local database?▼

Stripe subscription statuses are synchronized to local state using a deterministic mapping from Stripe events to state transitions. This mapping drives the state machine to update your database safely and consistently.

Can I enforce billing state transitions at both the application and database layers?▼

Yes, billing state transitions are enforced at both the database and application layers. This dual-layer approach uses database constraints and application-level guard logic to prevent invalid state changes and race conditions.

How do I trigger downstream effects like entitlements and audit logs on subscription state changes?▼

Downstream effects such as entitlements, emails, and audit logs are emitted on each state transition. The state machine uses pluggable transition effects to keep downstream systems in sync whenever a subscription state changes.

What's the best way to prevent invalid state changes in a SaaS billing system?▼

The best way to prevent invalid state changes is implementing a billing state machine with strict transition guards, optimistic locking, and database constraints. This provides a single source of truth for all subscription state modifications.