Article illustration 1

Building a reliable subscription billing system—one that handles plans, recurring charges, and invoicing without errors like double payments—is a formidable engineering challenge. For Medusa, the team behind the open-source commerce platform, the solution lay in their own toolbox. In a self-referential showcase of their technology's flexibility, they constructed the billing infrastructure for Medusa Cloud entirely using Medusa’s Commerce Modules and Framework, proving that modern commerce engines can power far more than just online stores.

The Billing Blueprint: From Plans to Payments

Medusa Cloud, a hosting platform that deploys and manages commerce applications, needed a way to manage customer subscriptions seamlessly. The requirements were straightforward but mission-critical: onboard users with plan selections, bill them monthly via saved payment methods, and issue invoices—all while ensuring atomic transactions to avoid financial discrepancies. As Oliver Juhl, Medusa engineer, outlined in the company's blog, this demanded a system that could handle billing cycles, background processing, and third-party payment integrations cohesively.

Instead of building from scratch, Medusa turned to its Data Model Language (DML) to define core billing entities like Subscription and Plan. Using simple schema definitions, they created relationships between organizations and their subscription tiers, automatically generating CRUD services:

// Simplified DML for Subscription model
export default model.define("subscription", {
  id: model.id({ prefix: "sub" }).primaryKey(),
  organization_id: model.text(),
  plan: model.belongsTo(() => Plan),
  current_period_start: model.dateTime(),
  current_period_end: model.dateTime()
});

These models became the foundation for workflows—Medusa’s system for orchestrating multi-step business logic. For instance, the createOrganisationSubscriptionWorkflow combines steps to fetch a plan, create a subscription, and link it to a customer’s organization. This abstraction allowed the team to compose complex operations from reusable, modular parts, minimizing boilerplate and ensuring consistency.

Automating Revenue Operations with Scheduled Jobs

With subscriptions established, the real test came in automating payments. Here, Medusa tapped into its existing Payment and Order modules, repurposing them for recurring billing. A scheduled job runs every five minutes to identify subscriptions ending their billing cycle, triggering a nested workflow:

  1. Create an order for the subscription fee.
  2. Initiate a payment collection using the customer’s stored method.
  3. Capture funds and mark the order as paid.
// Scheduled job configuration for payment collection
export default async function collectSubscriptionPayments(container) {
  await collectSubscriptionPaymentsWorkflow(container).run({
    input: { collectBeforeDate: new Date().getTime() }
  });
}

export const config = {
  name: "collection-subscription-payments",
  schedule: { interval: EVERY_5_MINUTES },
};

This setup leverages Medusa’s built-in capabilities for payments, refunds, and invoicing, reducing development overhead. The result? A system that handles hundreds of customer accounts—including enterprise clients—with reliability inherited from battle-tested commerce primitives.

Why This Matters for Developers and the Future of Commerce

Medusa’s approach underscores a broader shift: commerce tooling is evolving beyond storefronts into customizable engines for any monetization model. By using the same framework their customers employ, Medusa validated that developers can model unique scenarios—like SaaS subscriptions—without reinventing foundational features. Taxes, discounts, and multi-provider payments come out-of-the-box, accelerating time-to-market for niche use cases. As platforms increasingly blend services with transactions, this flexibility could redefine how teams build revenue operations, turning complex billing from a liability into a composable feature. For engineers, it’s a compelling case study in eating your own dog food—and finding it nourishes innovation.

Source: Building Medusa with Medusa: Billing