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 data models"
sidebarTitle: "Data models"
description: "Every field of PayoutAccount, Onboarding, Payout, and PayoutReversal, plus the payout enums."
---
The Payout module owns 4 data models: `PayoutAccount`, `Onboarding`, `Payout`, and `PayoutReversal`. They’re defined in `packages/core/src/modules/payout/models`, and the module service is registered as `MercurModules.PAYOUT`. Every model also gets Medusa’s `created_at`, `updated_at`, and `deleted_at` columns.
The module has no provider table and no `provider_id` columns: a marketplace has exactly one payout provider.
## PayoutAccount
A seller’s connection to the payout provider. Table `payout_account`, id prefix `pacc`.
| Field | Type | Description |
| --- | --- | --- |
| `id` | `text` | Primary key, such as `pacc_01JD8Q1234567` |
| `external_id` | `text`, nullable | The provider’s account id, such as a Stripe `acct_…` id. Unique when set, like `external_id` on Medusa’s `AccountHolder` |
| `status` | `enum` | `PayoutAccountStatus`, default `pending` |
| `kyc_status` | `enum`, nullable | `PayoutKycStatus`, derived from the provider’s requirements |
| `payouts_enabled` | `boolean` | Mirrors the provider, default `false` |
| `charges_enabled` | `boolean` | Mirrors the provider, default `false` |
| `details_submitted` | `boolean` | Mirrors the provider, default `false` |
| `disabled_reason` | `text`, nullable | The provider’s reason for disabling the account |
| `onboarding_token` | `text`, nullable | Secret for the public refresh URL. Unique when set, rotated on every refresh, cleared once details are submitted |
| `onboarding_token_issued_at` | `dateTime`, nullable | When `onboarding_token` was issued. The refresh URL rejects a token older than `onboarding.tokenTtlSeconds` |
| `last_synced_at` | `dateTime`, nullable | When the account was last read from the provider |
| `data` | `json` | The provider’s account object, default `{}`. Provider details such as outstanding requirements live here |
| `context` | `json`, nullable | Provider context passed at creation |
Relations:
- **`onboarding`**: `hasOne` `Onboarding`, nullable, mapped by `account`
- **`payouts`**: `hasMany` `Payout`, mapped by `account`
The seller is reached through the `seller_payout_account` link, not a column. See [Links](/platform/payout/reference/links).
## Onboarding
The provider’s onboarding state for one payout account. Table `onboarding`, id prefix `onb`.
| Field | Type | Description |
| --- | --- | --- |
| `id` | `text` | Primary key, such as `onb_01JD8Q1234567` |
| `data` | `json`, nullable | Provider link data plus `url`, `kind` (`onboarding` or `login`), and `expires_at` |
| `context` | `json`, nullable | Provider context from the last onboarding call |
| `account_id` | `text` | Foreign key to `PayoutAccount` |
Relations:
- **`account`**: `belongsTo` `PayoutAccount`, mapped by `onboarding`
## Payout
The seller’s share of one order, sent to their payout account. Table `payout`, id prefix `pout`.
| Field | Type | Description |
| --- | --- | --- |
| `id` | `text` | Primary key, such as `pout_01JD8Q1234567` |
| `display_id` | `autoincrement` | Human-readable sequence number |
| `order_id` | `text`, nullable | The order paid out. Unique when set, so an order is paid once |
| `currency_code` | `text` | Currency of the payout |
| `amount` | `bigNumber` | Order total minus commission, net of refunds that landed before the payout |
| `status` | `enum` | `PayoutStatus`, default `pending` |
| `status_reason` | `text`, nullable | A `PayoutStatusReason` code saying why the payout is on hold, failed, or aborted |
| `data` | `json`, nullable | `attempts`, `idempotency_key`, `status_detail` (the details behind `status_reason`), `source_payment`, `absorbed_refund_ids`, and the provider response under `provider`, whose `id` is the provider’s payout id, such as a Stripe transfer id |
| `metadata` | `json`, nullable | Your own data |
| `account_id` | `text` | Foreign key to `PayoutAccount` |
Relations:
- **`account`**: `belongsTo` `PayoutAccount`, mapped by `payouts`
- **`reversals`**: `hasMany` `PayoutReversal`, mapped by `payout`, deleted with the payout
Indexes, all limited to rows where `deleted_at IS NULL`:
- **`IDX_payout_account_id_created_at`**: on `account_id`, `created_at`
- **`IDX_payout_status_created_at`**: on `status`, `created_at`
- **`IDX_payout_order_id`**: unique on `order_id` when set
## PayoutReversal
One refund’s share taken back from a payout, the way Medusa keeps a `Refund` under a `Payment`. Table `payout_reversal`, id prefix `pourev`.
| Field | Type | Description |
| --- | --- | --- |
| `id` | `text` | Primary key |
| `refund_id` | `text`, nullable | The Medusa refund reversed. Unique when set |
| `amount` | `bigNumber` | The refund minus its share of the commission |
| `status` | `enum` | `PayoutStatus`, default `pending` |
| `status_reason` | `text`, nullable | A `PayoutStatusReason` code saying why the reversal is on hold, failed, or aborted |
| `data` | `json`, nullable | `attempts`, `idempotency_key`, `status_detail`, and the provider response under `provider`, whose `id` is the provider’s reversal id |
| `payout_id` | `text` | Foreign key to `Payout` |
Relations:
- **`payout`**: `belongsTo` `Payout`, mapped by `reversals`
## Enums
The enums are exported from `@mercurjs/types`.
`PayoutAccountStatus`:
| Member | Value |
| --- | --- |
| `PENDING` | `pending` |
| `ACTIVE` | `active` |
| `RESTRICTED` | `restricted` |
| `REJECTED` | `rejected` |
`PayoutKycStatus`:
| Member | Value |
| --- | --- |
| `PENDING_SUBMISSION` | `pending_submission` |
| `PENDING_APPROVAL` | `pending_approval` |
| `APPROVED` | `approved` |
| `REFUSED` | `refused` |
`PayoutStatus`, used by both `Payout` and `PayoutReversal`:
| Member | Value |
| --- | --- |
| `PENDING` | `pending` |
| `ON_HOLD` | `on_hold` |
| `PROCESSING` | `processing` |
| `PAID` | `paid` |
| `FAILED` | `failed` |
| `ABORTED` | `aborted` |