Account & Payout Account

Overview

Polar’s financial architecture is split across two distinct entities:

Entity	Table	Purpose	Required?
`Account`	`accounts`	Financial ledger — holds all transactions for an entity	Mandatory — every org has exactly one
`PayoutAccount`	`payout_accounts`	Payout configuration — holds Stripe Connect or manual bank details	Optional — created when the merchant is ready to receive payouts

This separation means:

Transaction history is never lost when a merchant changes their payout processor.
Multiple organisations can share a single PayoutAccount (e.g. a company with several Polar orgs pointing to one Stripe Connect account).
Accounts are created immediately on org creation — no held balances, no pending state.

`Account` Model

server/polar/models/account.py · table accounts The Account is a pure financial ledger. It has no Stripe credentials and no payout configuration. Its only job is to track money flowing in and out.

Key fields

currency: str              # Always "usd" (Polar's settlement currency)
credit_balance: int        # Denormalized sum of active promotional fee credits (cents)

# Platform fee overrides — None falls back to global settings
platform_fee_percent: int | None   # Basis points
platform_fee_fixed: int | None     # Fixed cents

processor_fees_applicable: bool    # False for manual/backoffice accounts

# Billing details for reverse invoices
billing_name: str | None
billing_address: Address | None    # JSONB-backed AddressType
billing_additional_info: str | None
billing_notes: str | None

admin_id: UUID             # FK → users.id

Fee calculation

def calculate_fee_in_cents(self, amount_in_cents: int) -> int:
    # (amount * basis_points / 10_000) + fixed_cents, rounded

Falls back to settings.PLATFORM_FEE_BASIS_POINTS / settings.PLATFORM_FEE_FIXED when the per-account overrides are None.

Credit balance

credit_balance is not the merchant’s earned revenue balance. It tracks promotional fee credits explicitly granted by Polar (manually by an admin, or via a campaign). Each credit is stored as an AccountCredit row; credit_balance is a denormalized running sum for fast reads. Credits are consumed against platform fees at payment time (not at payout): Credits are reduced in two cases:

Applied to a fee — account.reduce_credit_balance(amount_applied) after consuming AccountCredit rows
Revoked by admin — account.reduce_credit_balance(credit.amount) immediately

reduce_credit_balance(amount) subtracts min(amount, credit_balance), flooring at zero.

`PayoutAccount` Model

server/polar/models/payout_account.py · table payout_accounts The PayoutAccount holds all payout processor configuration. It is decoupled from the financial ledger so it can be swapped independently.

Types

Type	Description
`stripe`	Stripe Connect Express account
`manual`	Backoffice-managed; always considered payout-ready

Key fields

type: PayoutAccountType        # "stripe" | "manual"

stripe_id: str | None          # Stripe Connect account ID ("acct_...")
country: str                   # ISO-2; drives Stripe's regulatory requirements
currency: str                  # Stripe's default_currency
email: str | None              # Synced from Stripe

# Capability flags (always True for manual accounts)
is_details_submitted: bool
is_charges_enabled: bool
is_payouts_enabled: bool

business_type: str | None      # "individual" | "company" | etc.
data: dict                     # Full raw Stripe Account object (JSONB)

admin_id: UUID                 # FK → users.id

Payout readiness

@property
def is_payout_ready(self) -> bool:
    return self.type != PayoutAccountType.stripe or (
        self.is_payouts_enabled and self.stripe_id is not None
    )

Manual accounts are always ready. Stripe accounts require is_payouts_enabled=True.

`Organization` Relationships

server/polar/models/organization.py

# Mandatory — set at org creation, never NULL
account_id: UUID = mapped_column(
    ForeignKey("accounts.id", ondelete="restrict"),
    nullable=False,
    unique=True,        # enforces 1-to-1 at DB level
)

# Optional — set when merchant completes Stripe Connect onboarding
payout_account_id: UUID | None = mapped_column(
    ForeignKey("payout_accounts.id", ondelete="set null"),
    nullable=True,
)

unique=True on account_id enforces the 1-to-1 constraint at the DB level. payout_account_id has no unique constraint — multiple orgs can share a single PayoutAccount.

`Transaction` Model

server/polar/models/transaction.py · table transactions

account_id: UUID | None    # NULL → Polar's own transaction; NOT NULL → merchant/seller
payout_id: UUID | None     # Set when this transaction is swept in a Payout

account_id IS NOT NULL → transaction belongs to a specific merchant Account
account_id IS NULL → transaction is Polar’s own (e.g. collected fees, outgoing transfers)

Transaction types: payment, processor_fee, refund, refund_reversal, dispute, dispute_reversal, balance, payout, payout_reversal The future goal is to extend Account to represent customers and Polar subsidiaries too, enabling the full money trail to be traced in a single table:

`Payout` Model

server/polar/models/payout.py · table payouts A Payout links both entities, representing the transfer of funds from the merchant’s ledger to their payout processor.

account_id: UUID           # Source: merchant Account (NOT NULL)
payout_account_id: UUID    # Destination: PayoutAccount (NOT NULL)

currency: str              # "usd" (Polar's side)
amount: int                # cents
fees_amount: int           # cents

account_currency: str      # merchant's currency (may differ, e.g. "eur")
account_amount: int        # amount in merchant's currency

status: PayoutStatus       # pending | in_transit | succeeded | failed | canceled | held
processor: PayoutAccountType

invoice_number: str
invoice_path: str | None   # storage path; None until PDF is generated

Company

Working at Polar

Design

Engineering

Overview

`Account` Model

Key fields

Fee calculation

Credit balance

`PayoutAccount` Model

Types

Key fields

Payout readiness

`Organization` Relationships

`Transaction` Model

`Payout` Model

​Overview

​Account Model

​Key fields

​Fee calculation

​Credit balance

​PayoutAccount Model

​Types

​Key fields

​Payout readiness

​Organization Relationships

​Transaction Model

​Payout Model

Overview

`Account` Model

Key fields

Fee calculation

Credit balance

`PayoutAccount` Model

Types

Key fields

Payout readiness

`Organization` Relationships

`Transaction` Model

`Payout` Model