/polar-billing

name: polar-billing
description: "This skill should be used when working on Polar billing system, Stripe integration, subscription lifecycle, checkout flows, or benefit provisioning."
license: Apache-2.0

Polar Billing System

Comprehensive guide to Polar's billing infrastructure, covering entities, flows, Stripe integration, and benefit provisioning.

Quick Reference

Checkout → Payment → Order → Transaction → Benefits
                         ↓
                   Subscription (if recurring)
                         ↓
                   Subscription Cycle → Order → ...

Table of Contents

1. [Core Entities](#1-core-entities) 2. [Entity Relationships](#2-entity-relationships) 3. [Main Services](#3-main-services) 4. [Dramatiq Background Tasks](#4-dramatiq-background-tasks) 5. [Stripe Integration](#5-stripe-integration) 6. [Subscription Lifecycle](#6-subscription-lifecycle) 7. [Proration System](#7-proration-system) 8. [Benefits & Credits](#8-benefits--credits) 9. [Dunning & Payment Retry](#9-dunning--payment-retry) 10. [Transaction Ledger](#10-transaction-ledger) 11. [Key File Locations](#11-key-file-locations)

---

1. Core Entities

Checkout

**File:** `server/polar/models/checkout.py`

Shopping cart/payment session before order confirmation.

| Field | Type | Description | |-------|------|-------------| | `status` | CheckoutStatus | open, expired, confirmed, succeeded, failed | | `payment_processor` | PaymentProcessor | stripe, manual | | `client_secret` | str | Unique identifier for frontend | | `amount`, `currency` | int, str | Price in cents | | `tax_amount`, `discount_amount` | int | Calculated amounts | | `allow_trial`, `trial_end` | bool, datetime | Trial configuration | | `seats` | int | For seat-based products |

**Relationships:** organization, customer, product, product_price, discount, subscription (for upgrades)

---

CheckoutLink

**File:** `server/polar/models/checkout_link.py`

Persistent URL that creates Checkout Sessions on visit.

| Field | Type | Description | |-------|------|-------------| | `client_secret` | str | Unique identifier for the URL | | `seats` | int \| None | Preconfigured seat count for seat-based pricing | | `discount_id` | UUID \| None | Preset discount to apply | | `trial_interval`, `trial_interval_count` | Trial config | Override product trial settings |

**Relationships:** organization, products, discount

---

Order

**File:** `server/polar/models/order.py`

Represents a billing event (one-time purchase or subscription cycle).

| Field | Type | Description | |-------|------|-------------| | `status` | OrderStatus | pending, paid, refunded, partially_refunded | | `billing_reason` | OrderBillingReason | purchase, subscription_create, subscription_cycle, subscription_update | | `subtotal_amount` | int | Amount before discount/tax | | `discount_amount` | int | Discount applied | | `tax_amount` | int | Tax collected | | `applied_balance_amount` | int | Account balance applied | | `platform_fee_amount` | int | Polar's fee | | `refunded_amount` | int | Already refunded | | `next_payment_attempt_at` | datetime | Dunning retry time |

**Computed Properties:**

• `net_amount` = subtotal - discount
• `total_amount` = net + tax
• `due_amount` = max(0, total + applied_balance)
• `payout_amount` = net - platform_fee - refunded

---

Subscription

**File:** `server/polar/models/subscription.py`

Recurring billing relationship.

| Field | Type | Description | |-------|------|-------------| | `status` | SubscriptionStatus | incomplete, trialing, active, past_due, canceled, unpaid | | `amount`, `currency` | int, str | Subscription gross price | | `net_amount` | int | Net amount (gross minus inclusive tax, equal to gross if tax-exclusive) | | `tax_behavior` | TaxBehavior \| None | Inclusive, exclusive, or null (set at creation) | | `recurring_interval` | Interval | month, year | | `current_period_start/end` | datetime | Billing period | | `trial_start/end` | datetime | Trial period | | `cancel_at_period_end` | bool | Scheduled cancellation | | `canceled_at`, `ended_at` | datetime | Lifecycle timestamps | | `past_due_at` | datetime | When payment failed | | `seats` | int | For seat-based pricing |

**Relationships:** organization, customer, product, payment_method, discount, meters, grants (benefits)

---

Transaction

**File:** `server/polar/models/transaction.py`

All money flows in the system.

| Field | Type | Description | |-------|------|-------------| | `type` | TransactionType | payment, processor_fee, refund, dispute, balance, payout | | `processor` | Processor | stripe, manual | | `amount`, `currency` | int, str | Transaction amount | | `tax_amount` | int | Tax portion |

**Self-referential relationships:** payment_transaction, balance_transactions, incurred_transactions

---

Payment

**File:** `server/polar/models/payment.py`

Individual payment transaction.

| Field | Type | Description | |-------|------|-------------| | `status` | PaymentStatus | pending, succeeded, failed | | `processor_id` | str | Stripe charge ID | | `method` | str | card, bank_transfer, etc. | | `trigger` | PaymentTrigger \| None | What initiated payment: purchase, subscription_cycle, retry_dunning, retry_customer, retry_payment_method_update, retry_admin | | `decline_reason` | str | Why payment failed | | `risk_level`, `risk_score` | str, int | Fraud assessment |

---

Refund

**File:** `server/polar/models/refund.py`

| Field | Type | Description | |-------|------|-------------| | `status` | RefundStatus | pending, succeeded, failed, canceled | | `reason` | RefundReason | duplicate, fraudulent, customer_request, etc. | | `amount`, `tax_amount` | int | Refund amounts | | `revoke_benefits` | bool | Whether to revoke customer benefits |

---

Customer

**File:** `server/polar/models/customer.py`

| Field | Type | Description | |-------|------|-------------| | `email`, `name` | str | Contact info | | `billing_name` | str | Name for in