Medusa Development

Medusa Development

Medusa is a headless commerce framework built around modules, data models, and workflows; almost every piece of business logic — from an API route to a scheduled job — should be expressed as a workflow made of discrete, composable steps.

Workflow for Building a Medusa Feature

1. Define or extend the data model — Use the model utility from @medusajs/framework/utils to declare the module's data model(s) under src/modules/<module>/models/.
2. Write the module service — Create a service in src/modules/<module>/service.ts that extends MedusaService when the module has data models, exposing async methods for domain operations.
3. Register the module — Add the module to medusa-config.ts so Medusa's container can resolve it.
4. Build steps — Define each unit of work as a step with createStep from @medusajs/framework/workflows-sdk, including a compensation function for anything that needs to be undone on failure.
5. Compose the workflow — Wire steps together with createWorkflow, using transform for data shaping and when for conditional branches.
6. Expose the workflow — Call the workflow from an API route, a scheduled job, or a subscriber — never put business logic directly in the route/job/subscriber handler.
7. Read data with Query — Use Medusa's Query (req.scope.resolve("query") or the workflow-level useQueryGraphStep) to fetch data instead of calling module services directly for reads.

General Rules

• Don't use type aliases when importing files — import types and values directly from their source module rather than re-exporting through a local alias.
• When throwing errors, always throw MedusaError (from @medusajs/framework/utils) instead of a plain Error, so the API layer can map it to the correct HTTP status and error code.
• Always use Query to retrieve data rather than calling a module's service methods directly for reads — Query understands module links and can join data across modules in one call.

import { MedusaError } from "@medusajs/framework/utils"

if (!product) {
  throw new MedusaError(
    MedusaError.Types.NOT_FOUND,
    `Product with id "${productId}" was not found`
  )
}

Data Model Rules

• Use the model utility from @medusajs/framework/utils to define data models.
• Data model variables should be camelCase; the name passed to model.define should be snake_case.
• When adding an id field to a data model, always make it a primary key with .primaryKey().
• A data model can have only one id field — any other identifier should be a text field instead.
• Data model fields should be snake_case.

// src/modules/loyalty/models/loyalty-account.ts
import { model } from "@medusajs/framework/utils"

const LoyaltyAccount = model.define("loyalty_account", {
  id: model.id().primaryKey(),
  customer_id: model.text(),
  points_balance: model.number().default(0),
  tier: model.enum(["bronze", "silver", "gold"]).default("bronze"),
})

export default LoyaltyAccount

Service Rules

• When creating a service, always make its methods async.
• If a module has data models, make the service extend MedusaService so it inherits generated CRUD methods for each model.

// src/modules/loyalty/service.ts
import { MedusaService } from "@medusajs/framework/utils"
import LoyaltyAccount from "./models/loyalty-account"

class LoyaltyModuleService extends MedusaService({
  LoyaltyAccount,
}) {
  async addPoints(accountId: string, points: number) {
    const account = await this.retrieveLoyaltyAccount(accountId)
    return await this.updateLoyaltyAccounts({
      id: account.id,
      points_balance: account.points_balance + points,
    })
  }
}

export default LoyaltyModuleService

Workflow Rules

• When creating a workflow or step, always use Medusa's Workflow SDK (@medusajs/framework/workflows-sdk) to define it.
• When creating a feature in an API route, scheduled job, or subscriber, always create a workflow for it rather than inlining the logic in the handler.
• When creating a workflow, always create a step for each discrete unit of work in it.
• In workflows, use transform for any data transformation between steps — don't manipulate step output directly in the workflow function body.
• In workflows, use when to define conditional branches instead of a plain if around step calls.
• Don't use await when calling steps inside a workflow — step invocation returns a special reference the workflow engine resolves, and await-ing it breaks the workflow's ability to orchestrate compensation and retries.
• In workflows, don't make the workflow function itself async — the function body only describes the step graph, it doesn't execute imperatively.
• Don't add typing to a compensation function's input — the compensation function receives whatever the step's invoke function returned, and Medusa infers this automatically.
• Only use steps in a workflow — don't call services, Query, or other side-effecting code directly inside the workflow function; put that logic in a step.

// src/workflows/redeem-loyalty-points.ts
import {
  createStep,
  createWorkflow,
  StepResponse,
  transform,
  when,
  WorkflowResponse,
} from "@medusajs/framework/workflows-sdk"
import { MedusaError } from "@medusajs/framework/utils"
import { LOYALTY_MODULE } from "../modules/loyalty"
import LoyaltyModuleService from "../modules/loyalty/service"

type RedeemPointsInput = {
  accountId: string
  points: number
}

const deductPointsStep = createStep(
  "deduct-points-step",
  async (input: RedeemPointsInput, { container }) => {
    const loyaltyService: LoyaltyModuleService = container.resolve(LOYALTY_MODULE)
    const account = await loyaltyService.retrieveLoyaltyAccount(input.accountId)

    if (account.points_balance < input.points) {
      throw new MedusaError(
        MedusaError.Types.INVALID_DATA,
        "Insufficient points balance"
      )
    }

    const previousBalance = account.points_balance
    const updated = await loyaltyService.updateLoyaltyAccounts({
      id: account.id,
      points_balance: previousBalance - input.points,
    })

    return new StepResponse(updated, { accountId: account.id, previousBalance })
  },
  async (compensationInput, { container }) => {
    if (!compensationInput) return
    const loyaltyService: LoyaltyModuleService = container.resolve(LOYALTY_MODULE)
    await loyaltyService.updateLoyaltyAccounts({
      id: compensationInput.accountId,
      points_balance: compensationInput.previousBalance,
    })
  }
)

export const redeemLoyaltyPointsWorkflow = createWorkflow(
  "redeem-loyalty-points",
  (input: RedeemPointsInput) => {
    const account = deductPointsStep(input)

    const tierDowngrade = when(account, (acc) => acc.points_balance === 0)
      .then(() => {
        return transform({ account }, (data) => ({
          ...data.account,
          tier: "bronze" as const,
        }))
      })

    return new WorkflowResponse(account)
  }
)