Medusa v2 Workflow Compensation Cannot Cross the Process Boundary

The first time I saw this in production, the database was spotless and the customer was furious. Order rolled back, admin showed nothing, and the customer was holding a confirmation email with an order number that had never existed. I am Manoj, commerce and ERP implementation lead at Mith Tech in Bengaluru, and stitching Medusa to ERP and accounting systems is where this failure mode stops being theoretical.

What compensation actually promises

The Workflows SDK implements the saga pattern. A saga gives you semantic compensation — a reversing action you wrote — not atomic rollback. Steps are not wrapped in one database transaction; each step commits on its own. When a later step throws, the orchestrator walks back up the completed steps and calls the second function you passed to createStep, in reverse order, with the payload you stashed in StepResponse's second argument.

That is the whole contract, and it is honoured precisely. The problem is what people read into it.

Two details make the gap wider than it looks. First, a step created without a second function is not flagged as risky — createStep simply sets noCompensation = !compensateFn and moves on. The step becomes silently irreversible. Second, hooks are steps. createHook(name, input) compiles down to a createStep call with a no-op body that your handler replaces, so a hook handler's side effects sit on exactly the same side of the boundary as any other step's.

The simulator below walks completeCartWorkflow as it exists in v2.18.0. Pick where it fails and watch the two columns diverge:

How do you Case 1 — order.placed goes out before the payment is authorized?

Status: reported as #15122, closed not_planned on 24 May 2026 by a stale bot — not by a maintainer decision — and still present in v2.18.0.

In packages/core/core-flows/src/cart/workflows/complete-cart.ts at tag v2.18.0, emitEventStep for OrderWorkflowEvents.PLACED sits at line 648, inside the parallelize() block alongside createRemoteLinkStep, updateCartsStep, reserveInventoryStep and registerUsageStep. authorizePaymentSessionStep and addOrderTransactionStep run after that block. The ordering is exactly what the issue described; the line number drifted from roughly 594 at report time to 648 at v2.18.0, because the code moved and the bug did not.

The maintainer bot on the thread agreed with the diagnosis and named the fix — move the emit out of parallelize() so it runs after addOrderTransactionStep — then invited a community contribution. Nobody took it. Thirty-eight days later the stale bot closed the issue. It is worth being precise about that: this was not triaged and rejected, it was left alone until an automation swept it up.

"But events are buffered until the workflow succeeds." That is the design intent, and the docs say so. It is true on the happy path. It fails three ways in production:

1. The buffer is best-effort, not transactional. emitEventStep's compensation calls eventBus.clearGroupedEvents(eventGroupId, { eventNames }). The release-and-clear logic in workflow-export.ts wraps those calls in a .catch() that only writes a logger.warn. A failed clear on the compensation path means the message stays queued and is delivered anyway. The reporter's own log line was a failure to release grouped events.
2. eventGroupId is only auto-set on the outermost .run(). The code does context.eventGroupId ??= uniqId. If it is absent, emitEventStep's compensation returns early — a no-op — and the event went out ungrouped, meaning immediately.
3. Grouping defers the emit, never the subscriber's side effects. Once released, a subscriber that calls Stripe, your mail provider, or your ERP has left the process. Nothing in the SDK can reach it.

That third point is the whole article. The reporter's compensation failure was in create-remote-links — a step inside the same parallelize() block as the emit. The workflow returned an order to the caller, ran a compensation pass, and order.placed had already gone out.

How do you Case 2 — the refund workflow reports success after a partial failure?

Status: reported as #15306, closed not_planned on 12 June 2026. The fix, PR #15307, was closed unmerged.

packages/core/core-flows/src/payment/steps/refund-payments.ts is 71 lines at v2.18.0 and the step body is 27 of them. It pushes each paymentModule.refundPayment(refundInput) into an array with a .catch() that logs and returns nothing, then filters the settled results with isObject. Three consequences follow mechanically:

• The rejected promise is converted into a resolved void, so the step cannot fail.
• The void results are filtered out of existence — no count, no ids, no aggregate error.
• There is no compensation function at all. createStep is called with two arguments, so a downstream failure cannot even attempt to reconcile.

A fourth, smaller one: the log line says Error was thrown trying to cancel payment for a refund operation, so grepping production logs for refund misses these entirely.

And it is worse than the issue says. This part is our own reading of the v2.18.0 source, not something the issue reports: in packages/core/core-flows/src/payment/workflows/refund-payments.ts, the step's result is bound to refundedPayments, but the transform that builds orderTransactionData closes over { payments, input } — the requested refunds — and not over refundedPayments. addOrderTransactionStep then writes a negative order transaction for every refund you asked for, including the ones that threw at the provider. The workflow returns 200. The money never moved. Reconciliation shows the order as refunded.

PR #15307 proposed the right shape: return { refunded_payments, failed_refunds }, create transactions only for successes, and emit a refund-failed event on partial failure, with unit tests. The changeset bot flagged it as a major bump across 78 packages, which is a plausible reason it stalled — changing a public step's return type is a breaking change. It was closed unmerged. Do not wait for a patch here; wrap the workflow yourself.

How do you Case 3 — retrying a capture sends a different idempotency key?

Status: #16292 is OPEN, labelled requires-team, filed 3 August 2026. The companion PR #16293 is open and unmerged.

In PaymentModuleService, the public capturePayment calls capturePayment_ to mint a capt_... row, then calls capturePaymentFromProvider_, and on any error deletes the capture row and rethrows. capturePaymentFromProvider_ derives the provider idempotency key from that row: context: { idempotency_key: capture?.id }. The Stripe adapter forwards context.idempotency_key as Stripe's idempotencyKey at eleven call sites.

Stated precisely: the deduplication token is the primary key of a row created immediately before the provider call and destroyed immediately after a failed one. It has the lifetime of a single attempt, so it can never dedupe an attempt — which is the only thing an idempotency key is for.

The failure window is the ordinary one. Stripe receives and processes the capture; the response is lost to a timeout, a connection reset, a pod eviction. Medusa's catch deletes capt_A. A retry — a human in Admin, a step's maxRetries, a client re-POST — runs capturePayment_ again, creates capt_B, and sends capt_B as the key. Stripe sees a brand-new key for a brand-new request, and captures the funds a second time. Stripe's contract is keyed strictly on the string you send.

The same file gets this right everywhere else. Other capture-adjacent calls derive the key from long-lived ids — the payment session id, the payment id, the refund id. Capture is the one that uses an ephemeral id.

Do not confuse this with #16012, which is a different, adjacent bug that was fixed and closed as completed. Its fix is plainly visible in v2.18.0's capturePayment_ as a SET LOCAL lock_timeout plus SELECT ... FOR UPDATE critical section that serialises concurrent captures on the same payment row. That fix is correct and it landed. The comment above it is proud that "the lock is never held across the provider call" — which is correct engineering for database contention, and is also, exactly, the boundary where compensation stops working. Medusa fixed the race inside the transaction. The idempotency problem sits outside it and is still open. That contrast is the thesis of this article in one repository diff.

Where should the side effect go instead?

There are two candidate homes for a downstream trigger, and only one of them survives contact with a compensation pass. The comparator walks six real failure windows:

Two API facts matter here, and both are easy to get wrong.

There is no onFinish option on createWorkflow. Its config object is TransactionModelOptions and nothing else: timeout, store, retentionTime, storeExecution (deprecated), idempotent, schedule. If you have seen an onFinish in a createWorkflow call somewhere, it was invented.

There is an onFinish on .run(), typed as part of DistributedTransactionEvents, alongside onBegin, onStepSuccess, onCompensateBegin and the rest. It is real and useful — with a genuinely surprising caveat. The SDK wraps your onFinish in attachOnFinishReleaseEvents, and that wrapper returns early without calling you when the transaction state is FAILED or REVERTED. So with an Event Bus module registered, your onFinish fires only on success. Without an event bus, the wrapper calls it unconditionally, including on failures. Never put cleanup logic there.

And note the scope limit: events is per-call. It is not a way to attach a terminal hook to a core workflow you do not invoke yourself. POST /store/carts/:id/complete runs completeCartWorkflow for you; you never own that call site. For that case, the subscriber gate is the only pattern that works.

// src/subscribers/order-placed-erp-sync.ts
// Do NOT treat order.placed as proof the checkout succeeded.
// It is emitted from inside parallelize() in completeCartWorkflow,
// before authorizePaymentSessionStep — medusajs/medusa#15122.

import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
import { syncOrderToErpWorkflow } from "../workflows/sync-order-to-erp"

export default async function orderPlacedHandler({
  event: { data },
  container,
}: SubscriberArgs<{ id: string }>) {
  const query = container.resolve(ContainerRegistrationKeys.QUERY)

  // Re-read terminal state. The payload is { id } only — it carries
  // no proof that the transaction reached a successful terminal state.
  const { data: [order] = [] } = await query.graph({
    entity: "order",
    fields: ["id", "status", "transactions.id"],
    filters: { id: data.id },
  })

  // addOrderTransactionStep is the last meaningful write of
  // completeCartWorkflow. No transactions => not a placed order,
  // no matter what the event said.
  if (!order || !order.transactions?.length) {
    return
  }

  await syncOrderToErpWorkflow(container).run({
    input: { order_id: order.id },
    // transactionId lives in `context` — there is no top-level
    // transactionId on FlowRunOptions.
    context: { transactionId: `erp-sync:${order.id}` },
  })
}

export const config: SubscriberConfig = {
  event: "order.placed",
}

// ---------------------------------------------------------------
// Where you DO own the call site, .run() takes lifecycle events.
// There is NO onFinish option on createWorkflow — this is the only
// onFinish that exists, and it is typed as DistributedTransactionEvents.
//
//   const { result, errors } = await myWorkflow(req.scope).run({
//     input,
//     throwOnError: false,
//     events: {
//       onFinish: async ({ transaction, errors }) => {
//         if (errors?.length) return
//         // terminal side effect goes here
//       },
//     },
//   })
//
// Caveat: attachOnFinishReleaseEvents wraps your onFinish and returns
// early on FAILED / REVERTED when the Event Bus module is registered.

A note on honesty, since this post is about precision: every API name, option and type signature in those recipes is read from the tagged v2.18.0 source or from an official docs page. The example workflows themselves are illustrative compositions written for this article. They are not executed in CI, and erpClient stands in for whatever HTTP client you register in your container.

createWorkflow(
  { name: "my-workflow", idempotent: true },
  (input) => { /* ... */ }
)

What you cannot fix from userland

Being straight about the limits is more useful than a pattern that pretends they are not there.

You cannot reorder emitEventStep inside completeCartWorkflow — it is core-flows code. Your options are the orderCreated hook, which is better but still a step with releaseLockStep after it; the subscriber gate, which is the only genuinely safe one; or a fork.

You cannot make refundPaymentsStep fail. You can wrap refundPaymentsWorkflow in your own workflow and add a following step that re-reads the payments and throws if the refunds do not match what you asked for.

You cannot fix the capture idempotency key at all without writing your own payment provider that maintains its own key store — the key is minted in PaymentModuleService before your provider is ever called. Watch PR #16293.

And you will struggle to write an integration test that proves any of this. #15836 reported that medusaIntegrationTestRunner's afterEach returns before event-triggered workflows finish: the wait loop breaks the moment zero non-terminal executions exist, with no settle window, while events are released after the transaction is already done and the subscriber's own workflow row has not been inserted yet. It was closed not_planned on 15 July 2026. Give your test workflows a retentionTime so their execution rows survive as observable done rows, and assert on the follow-on workflow's effect rather than relying on the runner's teardown.

One more piece of honesty about the state of the field: outside GitHub, there is almost nothing written about this. We looked. The only substantive independent write-up we could find is a dev.to post by David Bartalos whose third bug is a stale workaround that kept re-emitting order.placed after the upstream fix landed, producing duplicate confirmation emails — real-world evidence that order.placed gets treated as a trigger for irreversible side effects. There is no Stack Overflow cluster and no Reddit thread on Medusa compensation boundaries. There is also no dedicated idempotency page in the Medusa docs; the surface is scattered across the store-executions and long-running-workflow pages and a TSDoc comment in source. That documentation gap is a legitimate reason developers get this wrong.

How do you At a glance — quick reference?

Frequently asked questions

Can Medusa workflows undo a Stripe charge automatically if a later step fails?. No. A workflow can only run a compensation function you wrote, and the only way to reverse a Stripe charge is to issue a refund — which is a brand-new money movement that can itself fail. Medusa gives you the saga pattern, not distributed transactions. Assume every external call is permanent the moment it succeeds, and design the reversal as a deliberate business action rather than an undo.

What happens if we do not fix this before going live?. The failure is quiet and it lands on your support team, not your error tracker. Customers get confirmation emails for orders that no longer exist. Your ERP accumulates sales orders with no matching Medusa record, so month-end reconciliation does not close. Refunds show as completed in the ledger while the money is still with you, which is the kind of discrepancy that becomes an audit finding. And a lost provider response during a capture retry can charge a customer twice. None of these throw an exception you can alert on — that is precisely why they are worth an afternoon before launch.

Compensation is in-process bookkeeping. The instant a step's effect leaves the Node process — an event released to a subscriber, an HTTP call to a payment provider, a write to your ERP — the SDK has no lever on it, and every one of the three bugs above is that single sentence wearing a different hat. Draw the boundary on your own workflow diagram, put your irreversible calls on the far side of a terminal-state gate, and give every one of them a key that outlives the attempt.