Medusa.js has no native subscription billing engine. That’s not a bug — it’s an architectural choice. Subscriptions are handled through Stripe Billing, which is the correct tool for recurring payment logic, dunning, invoicing, and failed payment handling. What Medusa provides is the commerce layer around it: products, orders, fulfillment, and customer data. Here’s what a complete subscription implementation looks like, what it costs to build, and how it compares to the Shopify subscription app ecosystem.
Why Medusa Doesn’t Have Native Subscriptions
Most ecommerce platforms that include “subscriptions” are wrapping Stripe Billing anyway — they’re just hiding the complexity behind a UI. Medusa makes the integration explicit rather than abstracted.
Stripe Billing is purpose-built for recurring revenue: it handles billing intervals, prorations, trial periods, metered usage, dunning sequences for failed payments, and tax calculations across jurisdictions. Building an equivalent subscription engine from scratch would be redundant and worse.
The trade-off is integration complexity. With Shopify and a subscription app like Recharge, you get a pre-built UI and a relatively smooth setup. With Medusa, you’re configuring the Stripe Billing integration and building the subscriber-facing UI yourself.
What a Medusa Subscription Setup Looks Like
A complete Medusa subscription implementation has three layers: Stripe Billing for payment logic, Medusa for order and fulfillment management, and a custom storefront for the subscriber experience.
Stripe Billing Configuration
In Stripe, you define your subscription products with prices. A subscription to a monthly coffee box at $49/month is a Stripe Price object attached to a Stripe Product. When a customer subscribes, Stripe creates a Subscription object and bills automatically on the interval you define.
Stripe handles the billing cycle, sends payment failure notifications, retries declined cards according to your dunning rules (typically 3–4 retries over 7–14 days), and generates invoices. This part works without any Medusa integration — it’s just Stripe.
Medusa Order Sync
The Medusa integration layer listens to Stripe webhooks. When Stripe successfully charges for a subscription renewal, a webhook fires — and your custom Medusa code creates a new order, triggers fulfillment, and updates inventory. When a charge fails and a subscription cancels, Medusa marks the customer’s subscription inactive and stops order generation.
This event-driven sync is the most technically demanding part of a subscription build. It needs to handle edge cases: what happens if the webhook fires twice? What if an order is created but fulfillment fails? These failure modes need explicit handling.
Subscriber-Facing Storefront
The subscriber experience — viewing upcoming deliveries, pausing or canceling a subscription, swapping products, updating payment methods — is entirely custom front-end work. Medusa’s storefront starter doesn’t include subscription management UI. You’re building it.
A functional subscriber portal typically includes:
- Subscription status and next billing date
- Pause / resume / cancel controls
- Delivery history and upcoming order preview
- Product swap or frequency change options
- Payment method update (handled through Stripe’s customer portal or a custom implementation)
What a Medusa Subscription Build Costs
The cost depends almost entirely on how complex your subscription logic is and how polished the subscriber experience needs to be.
Simple subscription store — single-product subscriptions, monthly billing, basic subscriber portal (view status, cancel, update payment): $25,000–$40,000
Mid-tier subscription platform — multiple products and frequencies, pause/resume, product swap, prorated plan changes, dunning configuration, basic analytics dashboard: $45,000–$75,000
Complex subscription business — metered billing or usage-based pricing, custom gift subscription flows, subscriber cohort analytics, multi-currency, deep CRM integration: $85,000–$150,000
These estimates include Medusa backend development, the Stripe Billing integration, and storefront development. They do not include ongoing Stripe fees (0.5%–0.8% of recurring revenue through Stripe Billing) or infrastructure costs ($300–$800/month for a production deployment).
Medusa Subscriptions vs. Shopify’s Subscription App Ecosystem
Shopify doesn’t have native subscription billing either. The standard solution is Recharge, which costs $99–$499/month depending on plan, plus 1%–1.9% transaction fees on all subscription orders. Bold Subscriptions and Skio are alternatives in a similar price range.
At $100,000 in monthly subscription revenue, Recharge’s 1% transaction fee alone is $1,000/month — $12,000/year — on top of the monthly software fee. Skio’s transaction fee is lower (0.25%–0.5%) at higher plans, but you’re still paying per-transaction fees indefinitely.
A Medusa implementation has no per-transaction subscription fee beyond what Stripe Billing itself charges (0.5% on subscription revenue for its billing features, plus standard Stripe processing at 2.9% + $0.30). You own the integration. There’s no third-party app whose pricing can change or whose roadmap you don’t control.
The math at $100K/month recurring:
- Recharge Pro ($499/month + 1%): ~$1,499/month = $17,988/year
- Medusa + Stripe Billing (infrastructure + Stripe Billing fee): ~$750–$1,200/month = $9,000–$14,400/year
Medusa becomes cheaper on pure running costs within 12–24 months after accounting for the higher upfront build cost. The crossover point depends on your GMV and which Recharge plan you’re comparing against.
The honest Shopify advantage: Recharge can be deployed in a week. A custom Medusa subscription build takes 3–5 months. If you’re pre-revenue or early-stage, that speed-to-market difference matters more than the fee arbitrage.
For a broader look at how Medusa compares to Shopify at scale, the Medusa.js vs Shopify Plus breakdown has the full cost modeling.
Key Technical Decisions in a Medusa Subscription Build
Before starting a Medusa subscription build, several architecture decisions need to be made. These affect both build time and long-term flexibility.
Stripe Customer Portal vs. Custom UI
Stripe offers a hosted Customer Portal — a pre-built UI where subscribers can manage their payment methods and subscription. Using it saves front-end development time but limits your ability to customize the experience. A fully custom subscriber portal gives you control over UX but adds 3–6 weeks of front-end development.
Most businesses at launch use the Stripe Customer Portal and upgrade to a custom experience later. That’s a reasonable approach — build the revenue engine first, polish the subscriber experience second.
Subscription-Specific Fulfillment Logic
Standard ecommerce fulfillment is triggered once per order. Subscriptions trigger fulfillment on a recurring schedule. If your fulfillment system is a 3PL, you need to confirm that they accept recurring order submissions through API rather than manual entry — and that your Medusa integration can handle the timing (orders submitted 24–48 hours before desired ship date, for example).
Failed Payment Handling
Stripe’s default dunning (automatic payment retry) works well. But what happens in your system when a charge ultimately fails? You need explicit logic: does the subscription pause? Does it cancel immediately? Does the customer receive an email from Medusa or from Stripe? Getting this wrong frustrates customers and costs you revenue.
What Medusa Subscriptions Are Not Good For
Medusa is overkill for a simple subscription business under $50,000/month in recurring revenue with standard subscription products. At that scale, Recharge on Shopify or a WooCommerce subscription plugin is faster, cheaper to launch, and easier to manage.
Medusa subscription builds make sense when:
- You need custom subscription logic that Recharge or Bold can’t accommodate
- You’re scaling past $200,000/month where transaction fees become significant
- Your subscription product has complex fulfillment (custom boxes, variable products, subscriber choices)
- You’re building subscription as part of a larger headless commerce platform that also has B2B or marketplace components
For growing ecommerce businesses evaluating whether Medusa is the right platform overall, our Medusa.js for growing ecommerce post covers the broader platform decision.
Subscription Metrics You Need to Track — and How Medusa Handles Them
A subscription business lives and dies by a handful of numbers: monthly recurring revenue (MRR), churn rate, failed payment rate, and lifetime value (LTV). How you track these determines whether you can actually manage the business.
Medusa doesn’t include subscription analytics out of the box. Stripe’s dashboard gives you MRR, subscriber count, and churn data for the Stripe Billing layer — but it doesn’t connect to Medusa’s order or fulfillment data. You need to decide where your source of truth lives and build the reporting accordingly.
The two common approaches are:
Stripe-as-source-of-truth — use Stripe’s billing analytics for subscriber metrics and Medusa for fulfillment operations. Reports pull from Stripe directly. Simple to implement, but you’re looking at two systems to understand your business.
Unified data warehouse — push both Stripe events and Medusa order events into a central analytics database (Redshift, BigQuery, or a simpler PostgreSQL schema). Build your own MRR dashboard that combines billing data with fulfillment and return data. More development work upfront (30–50 hours), but better long-term reporting.
The failed payment rate is particularly important for physical subscription products. A Shopify + Recharge setup handles this through Recharge’s dunning UI — you can see at a glance what percentage of your subscribers failed their last charge. With Medusa and Stripe Billing, you’re reading this from Stripe’s subscription analytics and building alerts that trigger when failed payment rates spike.
The Real-World Failure Modes to Design For
Most subscription builds that go wrong do so in edge cases, not the happy path. The happy path — new subscriber signs up, pays monthly, receives product — is straightforward. The edge cases are where complexity lives.
Concurrent webhook delivery: Stripe occasionally delivers the same webhook event more than once. If your Medusa order creation logic isn’t idempotent — designed to be safe if triggered twice — you’ll create duplicate orders. This is a well-known problem with a known solution (idempotency keys), but it requires explicit implementation.
Mid-cycle plan changes: A subscriber upgrades from monthly to quarterly mid-cycle. Stripe calculates the proration; Medusa needs to know that the next order interval has changed. The sync logic between Stripe’s subscription schedule and Medusa’s order generation schedule must handle this correctly.
Trial-to-paid conversion: Free trial subscribers who convert to paid need their first charge to trigger a Medusa order. Subscribers who don’t convert need their access revoked and their record updated. The Stripe webhook events for trial conversion are different from standard renewal events — they need separate handling.
Subscription pauses: A subscriber wants to skip a month. In Stripe Billing, this means pausing the subscription or using a pause collection. In Medusa, it means suppressing the order generation for that cycle without creating a fulfillment. If the pause logic isn’t built correctly, subscribers get charged but no order is created — or vice versa.
Building for these edge cases adds 20–30% to the development timeline compared to a happy-path-only implementation. It’s not optional if you’re operating at meaningful subscriber volume.
FAQ
Does Medusa.js have built-in subscription functionality? No. Medusa v2 does not include native subscription billing. Recurring payments are handled through Stripe Billing, and the Medusa layer manages order creation and fulfillment sync triggered by Stripe webhooks. You’re building the integration and the subscriber-facing UI.
What does a Stripe Billing integration with Medusa actually involve? You’re configuring Stripe Products and Prices for your subscription offerings, writing a webhook handler in Medusa that creates orders when Stripe charges succeed, and building the logic that maps subscription cancellations and pauses to order generation. It’s 60–120 hours of backend development depending on complexity.
How does dunning work in a Medusa subscription setup? Dunning — the automatic retry of failed payments — is handled by Stripe Billing, not by Medusa. You configure retry rules in Stripe (how many retries, on what schedule). Medusa listens for the final failure event via webhook and updates the subscription status accordingly. Customer communication on failed payments can be handled through Stripe or through your own email system.
Can subscribers manage their own subscriptions without contacting support? Yes, but you have to build that capability. A self-service subscriber portal is custom front-end work. You can accelerate this by using Stripe’s hosted Customer Portal for payment method management and building a lighter custom UI for subscription pausing and product swaps.
How does a Medusa subscription setup compare to WooCommerce Subscriptions? WooCommerce Subscriptions (the plugin by WooCommerce.com) costs $279/year and handles recurring billing natively within WordPress. For a standard subscription product with fixed billing intervals, it’s faster and cheaper to implement than Medusa. The trade-off is that WooCommerce Subscriptions is a plugin sitting on top of a monolithic platform — you don’t have the API-first flexibility of Medusa. For custom WooCommerce subscription builds, our WooCommerce development work covers the plugin configuration and custom development needed.
What’s the realistic timeline for a Medusa subscription build? A simple Medusa subscription store — one or two product types, monthly billing, basic subscriber portal — takes 10–16 weeks from start to launch. More complex subscription logic extends that to 5–7 months. Factor in testing time for billing edge cases: proration, trial expirations, payment failures, and concurrent webhook delivery all need explicit testing before you go live.
Can I migrate from Recharge on Shopify to Medusa subscriptions? Yes, but it’s not trivial. Active subscriptions need to be migrated from Recharge’s system to Stripe Billing objects, and subscriber payment methods need to be transferred (Stripe has a migration process for this). Customer data and order history need to move to Medusa. Plan 40–80 hours of migration work on top of the full build cost, and expect a 2–4 week parallel-running period where both systems operate simultaneously before cutover.
If you’re evaluating a subscription build and want a straight assessment of what it takes, see our fixed-price packages or reach out directly. We’ll tell you whether Medusa is the right tool for your volume and timeline — or whether a custom WooCommerce store with WooCommerce Subscriptions is the faster, cheaper path.