polar-billing

# 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...