Workflow Hooks

Basic Hook Pattern

Common Workflow Hooks

• createProductsWorkflow.hooks.productsCreated - After products are created
• createOrderWorkflow.hooks.orderCreated - After an order is created
• updateCartPromotionsWorkflow.hooks.setPromotionContext - Inject extra context into promotion computation (v2.15.0+)
• upsertTaxLinesWorkflow.hooks.setTaxLineContext, updateTaxLinesWorkflow.hooks.setTaxLineContext, updateOrderTaxLinesWorkflow.hooks.setTaxLineContext - Customize the context passed to tax calculation (v2.16.0+)
• Ask MedusaDocs for specific workflow hooks and their input parameters

Context hooks (setPromotionContext, setTaxLineContext) are the supported way to feed custom data into Medusa’s promotion and tax calculation instead of overriding the workflows:

When to Use Hooks vs Subscribers

Use workflow hooks when:

• The logic must complete before the workflow finishes
• You need rollback/compensation capabilities
• The operation is critical to the workflow’s success

Use subscribers when:

• The logic can run asynchronously in the background
• You don’t need to block the main workflow
• Better performance is needed (hooks are synchronous)

Hook Best Practices

1. Return StepResponse: Always wrap your return value
2. Implement compensation: Provide rollback logic for the compensation function
3. Handle missing data gracefully: Check for optional data and return early if not present
4. Keep hooks lightweight: For heavy operations, consider using subscribers instead