The complete open source platform to run your entire marketplace. Storefront, vendor panel, admin console, and integrations in one enterprise-grade platform you own.
TypeScript b2b-marketplacecomposable-commerceecommerceenterpriseheadless-commercemarketplacemedusamedusajsmulti-vendortypescript
---
title: "Payout events"
sidebarTitle: "Events"
description: "The payout webhook event, the events the payout workflows emit, and the data-model events of the Payout module."
---
The Payout module’s events are named in `PayoutModuleEvents` from `@mercurjs/types`. `payout.webhook_received` carries provider webhooks to the shipped subscriber; the others come from the payout workflows. Medusa also emits a created, updated, or deleted event whenever a payout record changes. Subscribe to these for side effects such as seller notifications or operator alerts.
## PayoutModuleEvents
| Member | Name | Emitted by | Payload |
| --- | --- | --- | --- |
| `WEBHOOK_RECEIVED` | `payout.webhook_received` | `POST /hooks/payout` | `{ data, rawData, headers }` |
| `ACCOUNT_UPDATED` | `payout_account.updated` | `syncPayoutAccountWorkflow` | `{ id }` |
| `PAYOUT_FAILED` | `payout.failed` | `createOrderPayoutsWorkflow`, `processPayoutWorkflow` | `{ id }` |
| `PAYOUT_REVERSAL_FAILED` | `payout.reversal_failed` | `createPayoutReversalsWorkflow`, `processPayoutReversalWorkflow` | `{ id }` |
Like Medusa’s payment events, the payloads carry only the row’s id; retrieve the account, payout or reversal in the subscriber for anything else. `payout.failed` and `payout.reversal_failed` are emitted once per row that the provider refused in that run. A row the provider refused for good is `aborted` and emits nothing.
## Webhook event
The `POST /hooks/payout` route emits `payout.webhook_received` with a 5000 ms delay and 3 attempts. `data` is the parsed body, `rawData` is the raw body, and `headers` are the request headers.
The `payout-webhook` subscriber, with subscriber id `payout-webhook-handler`, parses it through the provider and runs `processPayoutForWebhookWorkflow`. The event bus serializes `rawData` as a buffer object, and the subscriber turns it back into a `Buffer` before signature checks. Other subscribers can listen to the same event; the Stripe connector plugin uses it to record bank payout events on its settlements.
## Data-model events
`PayoutModuleService` extends `MedusaService`, so Medusa emits an event for each row it creates, updates, or deletes. The name is the module name, the kebab-case model name, and the action. The payload is `{ id }`.
| Event | Emitted when |
| --- | --- |
| `payout.payout-account.created` | `createPayoutAccount` inserts an account |
| `payout.payout-account.updated` | The provider response is stored, or a sync refreshes the account |
| `payout.payout-account.deleted` | The provider call fails and the new account is removed, or a rollback deletes it with `deletePayoutAccount` |
| `payout.onboarding.created` | `createOnboarding` runs for the first time on an account |
| `payout.onboarding.updated` | `createOnboarding` runs again on the same account |
| `payout.payout.created` | `createOrderPayoutsWorkflow` inserts a payout |
| `payout.payout.updated` | A payout is re-decided, sent, or changed by a webhook |
| `payout.payout-reversal.created` | `createPayoutReversalsWorkflow` inserts a reversal |
| `payout.payout-reversal.updated` | A reversal is re-decided or sent |
An `updated` event fires for every write. Subscribe to `payout_account.updated` instead when you only care about provider syncs, and read the account’s new status in the subscriber:
```ts title="src/subscribers/payout-account-updated.ts"
import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
import {
IPayoutModuleService,
MercurModules,
PayoutAccountStatus,
PayoutModuleEvents,
} from "@mercurjs/types"
export default async function payoutAccountUpdated({
event,
container,
}: SubscriberArgs<{ id: string }>) {
const payoutService = container.resolve<IPayoutModuleService>(MercurModules.PAYOUT)
const account = await payoutService.retrievePayoutAccount(event.data.id)
if (account.status === PayoutAccountStatus.RESTRICTED) {
const logger = container.resolve("logger")
logger.warn(`Payout account ${account.id} is restricted`)
}
}
export const config: SubscriberConfig = {
event: PayoutModuleEvents.ACCOUNT_UPDATED,
}
```
This subscriber logs a warning each time an account lands in `restricted`, which is where you’d send the seller a reminder to finish onboarding.
## Workflow hook
`createOrderPayoutsWorkflow` exposes a `payoutsCreated` hook with `{ order_ids, payouts }`, where `payouts` are the payouts sent to the provider in that run. Use it when you need the order ids with the result.