Stripe Subscriptions for Medusa v2

Subscriptions Change Everything
Recurring revenue transforms e-commerce businesses. Instead of one-time purchases, you build predictable income streams. Customers get convenience, you get stability.
That's why we built the Subscription Plugin for Medusa — a complete recurring billing system that integrates seamlessly with Stripe and your existing Medusa store.
What It Does
The plugin adds full subscription management to your Medusa store:
Automatic Subscription CreationWhen a customer purchases a product with subscription configuration, we automatically create both a Stripe subscription and a Medusa subscription record. Payment method is captured from checkout and attached for future billing.
Stripe Billing IntegrationStripe handles all the heavy lifting: recurring charges, payment retries, proration, and invoice generation. Your subscriptions just work.
Pause and ResumeNeed to pause a subscription? Both admin and webhook-triggered pauses are supported. Set an automatic resume date or resume manually. Medusa stays in sync with Stripe.
Status TrackingTrack subscription lifecycle: Active → Paused → Cancelled → Expired → Failed. Status syncs automatically from Stripe webhooks.
Customer DashboardCustomers can view their subscriptions, see billing dates, check renewal history, and cancel directly from their account.
Payment Methods ManagementSaved payment methods are displayed in the customer dashboard. Set default, remove cards — all managed through Stripe's secure infrastructure.
How We Built It
The plugin follows Medusa v2 patterns:
Custom ModuleSelf-contained subscription management with its own service, repository, models, and types. Extends MedusaService for standard CRUD operations plus custom methods for subscription lifecycle.
Remote LinksProper relationships between subscriptions, customers, and orders using Medusa's remote link system. Query subscriptions with their linked data seamlessly.
Event-Driven WebhooksSubscriber pattern handles Stripe webhook events. When Stripe sends invoice.payment_succeeded, we record the renewal. When customer.subscription.updated arrives, we sync the status.
Admin APIFull CRUD for subscriptions in the admin dashboard. View all subscriptions, pause, resume, cancel — all synced to Stripe.
Store APICustomer-facing endpoints for viewing and managing their own subscriptions with proper ownership verification.
Plugin File Structure
Backend:- src/modules/subscription/ — Core module (service, models, types, migrations)- src/links/ — Remote links (subscription-customer, subscription-order)- src/subscribers/ — Event handlers (order.placed, payment.webhook_received)- src/api/admin/subscriptions/ — Admin endpoints- src/api/store/customers/me/subscriptions/ — Customer endpoints- src/api/store/customers/me/payment-methods/ — Payment methods API- src/lib/stripe.ts — Stripe integration helpers
Storefront:- src/lib/data/subscriptions.ts — Server actions- src/lib/data/payment-methods.ts — Payment method actions- src/modules/account/components/subscription-card/ — Subscription display- src/modules/account/components/payment-methods/ — Payment method management
Stripe Integration
The plugin orchestrates multiple Stripe resources:
Stripe CustomerCreated with medusa_customer_id in metadata for cross-system linking. Searched by metadata on subsequent purchases.
Stripe Product & PriceProducts created with medusa_product_id metadata. Prices created with recurring configuration matching the subscription interval.
Stripe SubscriptionCreated with billing_cycle_anchor for proper billing timing. Payment method attached from checkout PaymentIntent.
Webhook SyncHandles customer.subscription.updated, customer.subscription.deleted, invoice.payment_succeeded, and invoice.payment_failed. Keeps Medusa in perfect sync with Stripe state.
Subscription Lifecycle
Order Placed → Check items for subscription config↓Create Stripe Customer (or find existing)↓Create Stripe Product & Price↓Attach Payment Method from PaymentIntent↓Create Stripe Subscription↓Create Medusa Subscription + Remote Links↓Webhook Events keep systems in sync↓Customer views/manages via dashboard
Configuration
Environment variables:
STRIPE_API_KEY=sk_live_xxxSTRIPE_WEBHOOK_SECRET=whsec_xxx
The plugin uses your existing Stripe payment provider configuration. No additional setup required if Stripe is already configured.
Key Features
- Automatic subscription creation from checkout- Stripe-managed recurring billing- Pause/resume with optional auto-resume date- Payment method management in customer dashboard- Webhook sync for status updates- Remote links for customer/order relationships- Admin dashboard for subscription management- Customer self-service cancellation
What's Next
We're actively developing:- Subscription plan upgrades/downgrades- Proration handling- Trial periods- Usage-based billing- Email notifications for renewals and failures
Open Source
This plugin is part of our commitment to the Medusa ecosystem. Check out the code:
GitHub: github.com/cloud1media/medusa-plugin-subscriptions
We'd love your feedback. If you're building subscriptions on Medusa, reach out — we're happy to help.