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
2. Entity Relationships
3. Main Services
4. Dramatiq Background Tasks
5. Stripe Integration
6. Subscription Lifecycle
7. Proration System
8. Benefits & Credits
9. Dunning & Payment Retry
10. Transaction Ledger
11. Key File Locations

---

1. Core Entities

Checkout

File: server/polar/models/checkout.py

Shopping cart/payment session before order confirmation.

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

---

Order

File: server/polar/models/order.py

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

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.

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

---

Transaction

File: server/polar/models/transaction.py

All money flows in the system.

Self-referential relationships: payment_transaction, balance_transactions, incurred_transactions

---

Payment

File: server/polar/models/payment.py

Individual payment transaction.

---

Refund

File: server/polar/models/refund.py

---

Customer

File: server/polar/models/customer.py

---

Product & ProductPrice

Files: server/polar/models/product.py, server/polar/models/product_price.py

---

BillingEntry

File: server/polar/models/billing_entry.py

Audit log for billing calculations.

---

2. Entity Relationships

Organization
├── Product
│   ├── ProductPrice (multiple per product)
│   └── ProductBenefit → Benefit
├── Customer
│   ├── Subscription → Product, Discount
│   │   ├── SubscriptionProductPrice
│   │   ├── SubscriptionMeter
│   │   └── BenefitGrant
│   ├── Order → Product, Subscription
│   │   └── OrderItem
│   ├── PaymentMethod
│   └── Wallet
├── Checkout → Customer, Product
├── Discount
│   └── DiscountRedemption
└── Account (for payouts)
    └── Payout → Transaction

Transaction (ledger)
├── payment → Order, Customer
├── refund → Refund, Order
├── dispute → Dispute, Order
├── processor_fee → parent payment
└── payout → Account

---

3. Main Services

SubscriptionService

File: server/polar/subscription/service.py

Core subscription operations:

# Creation
create_or_update_from_checkout(checkout, payment_method) → (Subscription, created)

# Updates
update_product(subscription, product_id, proration_behavior)
update_seats(subscription, seats, proration_behavior)
update_discount(subscription, discount_id)
update_trial(subscription, trial_end)

# Lifecycle
cycle(subscription)  # Period renewal
cancel(subscription)  # At period end
revoke(subscription)  # Immediately
uncancel(subscription)

# Benefits
enqueue_benefits_grants(task="grant"|"revoke", customer, product)

OrderService

File: server/polar/order/service.py

create_from_checkout(checkout)  # One-time purchase
create_subscription_order(subscription, billing_reason)  # Recurring
trigger_payment(order)  # Charge customer
create_order_balance(order)  # Ledger entries

CheckoutService

File: server/polar/checkout/service.py

create(product, customer_data, discount_code)
confirm(checkout)  # Lock checkout for payment
handle_stripe_success(checkout, charge)
handle_free_success(checkout)  # No payment needed

PaymentService

File: server/polar/payment/service.py

upsert_from_stripe_charge(charge, checkout, order)
handle_success(payment)  # Complete order
handle_failure(payment)  # Update order status

RefundService

File: server/polar/refund/service.py

create(order, amount, reason, revoke_benefits)
upsert_from_stripe(stripe_refund)

BenefitGrantService

File: server/polar/benefit/grant/service.py

enqueue_benefits_grants(task, customer, product, order=None, subscription=None)
grant_benefit(customer, benefit)
revoke_benefit(customer, benefit)

---

4. Dramatiq Background Tasks

Subscription Tasks

File: server/polar/subscription/tasks.py

Order Tasks

File: server/polar/order/tasks.py

Stripe Webhook Tasks

File: server/polar/integrations/stripe/tasks.py

Benefit Tasks

File: server/polar/benefit/tasks.py

Checkout Tasks

File: server/polar/checkout/tasks.py

Payout Tasks

File: server/polar/payout/tasks.py

---

5. Stripe Integration

Webhook Endpoints

File: server/polar/integrations/stripe/endpoints.py

• /v1/integrations/stripe/webhook - Direct webhooks
• /v1/integrations/stripe/webhook-connect - Connect account webhooks

Implemented Webhooks

Payment Flow:

• payment_intent.succeeded - Payment complete
• payment_intent.payment_failed - Payment failed
• setup_intent.succeeded - Card saved
• charge.pending/failed/succeeded/updated - Charge lifecycle

Refunds:

• refund.created/updated/failed

Disputes:

• charge.dispute.created/updated/closed

Connect:

• account.updated - Account info changed
• payout.updated/paid - Payout lifecycle

Webhook Processing Flow

Stripe POST → Verify signature → ExternalEvent.enqueue()
                                        ↓
                               Store in external_events table
                                        ↓
                               Enqueue Dramatiq task
                                        ↓
                               Worker processes async
                                        ↓
                               Mark handled_at on success

StripeService

File: server/polar/integrations/stripe/service.py

Key methods:

• create_payment_intent(), create_setup_intent()
• create_refund(), get_refund()
• create_tax_calculation(), create_tax_transaction()
• transfer(), create_payout()

---

6. Subscription Lifecycle

Creation Flow

1. Checkout created (status=open)
2. Customer completes payment
3. Stripe charge.succeeded webhook
4. payment.handle_success() called
5. checkout_service.handle_stripe_success()
6. subscription_service.create_or_update_from_checkout()
   - Creates Subscription (status=active or trialing)
   - Sets billing period
   - Applies discount
   - Resets meters
7. Enqueue benefit grants
8. Send confirmation email

Cycle Flow (Renewal)

1. APScheduler triggers at period end
2. subscription.cycle task runs
3. subscription_service.cycle()
   - Check cancel_at_period_end
   - If true: set status=canceled, revoke benefits
   - If false: advance period dates, check discount expiry
4. Create billing entry (type=cycle)
5. Enqueue order.create_subscription_order
6. Order created with billing_reason=subscription_cycle
7. Enqueue order.trigger_payment
8. Stripe charges payment method
9. charge.succeeded → ledger entries → benefits renewed

Cancellation Flow

At Period End:

subscription_service.cancel(subscription)
# Sets cancel_at_period_end=True, ends_at=current_period_end
# Benefits remain until period ends
# On next cycle: status=canceled, benefits revoked

Immediately:

subscription_service.revoke(subscription)
# Sets status=canceled, ended_at=now
# Benefits revoked immediately
# Seats canceled if seat-based

Trial Flow

1. Checkout with trial_end set
2. Subscription created with status=trialing
3. No payment during trial
4. At trial_end, cycle task runs
5. Status transitions to active
6. Order created with billing_reason=subscription_cycle_after_trial
7. First payment charged

---

7. Proration System

When Prorations Occur

1. Product change - Upgrade/downgrade to different tier
2. Seat change - Add/remove seats
3. Interval change - Monthly to yearly

Proration Calculation

# Calculate time remaining in period
pct_remaining = (period_end - now) / (period_end - period_start)

# Old product credit (what they paid but won't use)
old_credit = old_price * old_pct_remaining

# New product debit (what they owe for remainder)
new_debit = new_price * new_pct_remaining

# Net proration
net = new_debit - old_credit

Proration Behaviors

BillingEntry for Prorations

# Credit entry (old product)
BillingEntry(
    type=BillingEntryType.proration,
    direction=BillingEntryDirection.credit,
    amount=prorated_old_amount
)

# Debit entry (new product)
BillingEntry(