Subscription Commerce

The Hidden Complexity of Recurring Billing

We built the Subscription Commerce skill because we watched too many engineering teams treat subscription logic as an afterthought. You don't build a subscription feature by slapping a stripe.subscriptions.create call into your checkout controller and hoping for the best. Subscriptions are state machines. They are lifecycle management systems. They require handling the happy path, yes, but also the unhappy path: card declines, expired cards, insufficient funds, address verification failures, proration calculations, tax changes, currency conversions, and dunning workflows.

The architecture implication is that your billing layer needs to be separate from your payment gateway, configurable for retry logic, and isolated from your core application logic ^[2]. When you mix them, you get a spaghetti codebase that breaks when you want to switch providers, add a new dunning rule, or comply with a new regulation. You're also ignoring the retention aspect. Subscriptions depend on recurring payments, but this comes with additional rules and compliance requirements from global governments and card networks ^[8]. Most teams treat dunning as an email template. That's a mistake. Dunning is a nuanced revenue recovery strategy ^[1]. If you hardcode your billing logic, you're not just wasting engineering time; you're actively designing for churn.

Why "Just Use Stripe" Fails at Scale

Ignoring the architecture leads to revenue leakage. If your retry logic is naive, you churn customers who are just waiting for a retry window. Dunning is nuanced, and the best strategy reflects a specific understanding of your customer base ^[1]. A bad strategy costs you MRR. Every failed renewal is a support ticket. Every support ticket is a customer acquisition cost hit. You're spending engineering hours debugging proration edge cases instead of building features. You're also risking compliance violations. If you don't handle data governance and compliance setup properly, you're exposing the company to risk.

The cost of a single major billing outage can be weeks of lost revenue and reputational damage. You're building a custom dunning system when you should be configuring a proven one. The absence of best practices leads to mismanagement of billing, renewals, and customer experience ^[6]. You're also missing out on the benefits of recurring payments, like predictable revenue and reduced friction for customers ^[4]. But without the right architecture, those benefits never materialize. You're stuck in a cycle of firefighting. Every time a payment fails, you're manually investigating. Every time a customer wants to pause, you're writing a custom API endpoint. Every time you want to change your dunning strategy, you're redeploying your entire app.

We see this pattern repeatedly. Teams start with a simple payment integration, then realize they need proration, then realize they need dunning, then realize they need compliance. By the time they get there, their codebase is a mess. They've hardcoded provider-specific logic. They've mixed billing state with user state. They've forgotten to validate their JSON schemas. They've deployed untested retry intervals. And now they're losing MRR because their dunning strategy is broken.

A Hypothetical Fintech's Billing Nightmare

Imagine a team shipping a subscription feature for a SaaS product. They use Stripe Checkout. It works for the first month. Then a card expires. The payment fails. They have no dunning strategy. They send an email. The customer ignores it. The subscription cancels. They lose the MRR. They realize they need a proper dunning strategy ^[1]. They try to integrate Recurly. They spend weeks configuring retry intervals, pause workflows, and renewal requests. They mess up the JSON schema. The validation fails in staging. They lose a week. Contrast this with a team that uses a structured workflow. They define the subscription models first. They integrate the payment gateway with a production-grade template. They configure the dunning strategy against a schema. They validate before deployment. They ship faster. They retain more customers.

A 2024 analysis of subscription eCommerce models shows that recurring billing, subscription management, and retention automation are key to growing predictable revenue ^[3]. The team that follows the workflow gets there faster. They don't guess. They don't hardcode. They don't deploy untested logic. They use a skill that orchestrates the entire lifecycle. They define the models. They integrate the gateway. They implement the billing logic. They configure the dunning. They build retention. They validate compliance. And they ship.

This isn't just about saving time. It's about revenue. Every hour you spend debugging proration is an hour you're not spending on growth. Every failed renewal is a customer you're losing. Every support ticket is a cost you're incurring. You need a system that handles the complexity so you don't have to. You need a skill that orchestrates the workflow, validates the configuration, and ships production-grade code. You need the Subscription Commerce skill.

What Changes Once the Workflow Is Locked

Once the skill is installed, the agent handles the heavy lifting. Phase 1 defines the models. Phase 2 integrates Stripe with a React/TypeScript template that includes fields configuration and error handling. Phase 3 implements the billing logic. Phase 4 configures Recurly dunning with a JSON template that defines retry intervals and strategy types. Phase 5 builds retention mechanisms. Phase 6 validates compliance and security. The validate-config.sh script runs before deployment, checking the JSON schema. The subscription-schema.json catches errors. The stripe-payment-element.tsx is production-grade. The recurly-dunning-config.json is ready.

You stop guessing retry intervals and start using best practices ^[1]. You get predictable revenue ^[4]. You can also pair this with other skills like invoice billing for end-to-end automation, or dynamic pricing for advanced strategies. You can even integrate churn predictors to save at-risk customers. You can sync your real-time inventory to prevent overselling. You can orchestrate your payment flows for maximum reliability. You can optimize your visual merchandising to increase conversion. And you can personalize your product recommendations to increase LTV.

The skill doesn't just generate code. It enforces architecture. It separates billing from payments. It configures dunning against a schema. It validates compliance. It ships production-grade templates. It handles the edge cases. It saves you weeks of engineering time. It protects your MRR. It scales with your business. It's the subscription commerce workflow you should have built from day one.

What's in the Subscription Commerce Pack

• skill.md — Orchestrator skill definition. Defines the Subscription Commerce workflow (Phases 1-6), references all templates, references, validators, and examples. Guides the agent to use Stripe for payment collection and Recurly for lifecycle/dunning management.
• templates/stripe-payment-element.tsx — Production-grade React/TypeScript template for Stripe Payment Element integration. Includes fields configuration, error handling, and confirmation logic based on Stripe docs.
• templates/recurly-dunning-config.json — JSON template for Recurly dunning strategy configuration. Defines retry intervals, actions, and strategy types (standard, retry-after, retry-before) per Recurly docs.
• scripts/validate-config.sh — Executable validator script. Checks subscription configuration files against the JSON schema using jq. Exits non-zero on validation failure. Ensures dunning and payment configs are structurally valid.
• validators/subscription-schema.json — JSON Schema definition for subscription configurations. Validates structure of dunning strategies, payment element options, and subscription metadata.
• references/stripe-payment-elements.md — Embedded canonical knowledge from Stripe docs. Covers Payment Element creation, fields configuration (billing details, address), and confirmation methods (EPS, Bancontact, SetupIntent).
• references/recurly-dunning-strategies.md — Embedded canonical knowledge from Recurly docs. Covers dunning strategies, retry intervals, pause/postpone workflows, subscription terms, and renewal requests.
• examples/subscription-onboarding-flow.md — Worked example demonstrating a complete subscription onboarding flow. Integrates Stripe Payment Element setup with Recurly subscription creation and dunning configuration.

Stop Guessing, Start Shipping

Subscription commerce isn't a side project. It's your revenue engine. Don't let it break because you hardcoded the billing logic. Upgrade to Pro to install the Subscription Commerce skill. Stop building dunning from scratch. Start shipping production-grade subscription workflows. Install the skill. Define the models. Integrate the gateway. Configure the dunning. Validate the config. Ship.