Name: Polar Billing
Author: fcakyon

搵技能.../

Polar Billing | Skills Pool

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

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

Field	Type	Description
`status`	SubscriptionStatus	incomplete, trialing, active, past_due, canceled, unpaid
`amount`, `currency`	int, str	Subscription price
`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

Field	Type	Description
`status`	PaymentStatus	pending, succeeded, failed
`processor_id`	str	Stripe charge ID
`method`	str	card, bank_transfer, etc.
`decline_reason`	str	Why payment failed
`risk_level`, `risk_score`	str, int	Fraud assessment

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

ProductPrice Types	Description
`ProductPriceFixed`	Fixed amount
`ProductPriceCustom`	Merchant sets at checkout
`ProductPriceFree`	Zero cost
`ProductPriceMeteredUnit`	Pay-per-unit
`ProductPriceSeatUnit`	Per-seat with tiers

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

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

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

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

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

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

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

Task	Trigger	Action
`subscription.cycle`	Scheduler at period end	Renew subscription, create order
`subscription.update_product_benefits_grants`	Product benefits changed	Update all grants
`subscription.cancel_customer`	Customer deleted	Cancel all subscriptions

Task	Trigger	Action
`order.create_subscription_order`	Subscription cycle	Create billing order
`order.trigger_payment`	Order ready	Charge payment method
`order.balance`	Payment success	Create ledger entries
`order.invoice`	Order created	Generate PDF invoice
`order.process_dunning`	Hourly cron	Find orders for retry
`order.process_dunning_order`	Individual retry	Retry single payment

Task	Stripe Event	Action
`charge.succeeded`	Payment complete	Create order, provision benefits
`charge.failed`	Payment failed	Mark order failed
`charge.updated`	Charge settled	Create ledger transaction
`refund.created/updated`	Refund processed	Update refund record
`charge.dispute.created`	Chargeback	Create dispute, revoke benefits
`payout.paid`	Payout complete	Update payout status

Task	Trigger	Action
`benefit.enqueue_benefits_grants`	Order/subscription	Queue individual grants
`benefit.grant`	Individual benefit	Provision access (GitHub, Discord, etc.)
`benefit.revoke`	Cancellation/refund	Remove access
`benefit.cycle`	Subscription renewal	Reset credits with rollover

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

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

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

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

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

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

# 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

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

# Debit entry (new product)
BillingEntry(
    type=BillingEntryType.proration,
    direction=BillingEntryDirection.debit,
    amount=prorated_new_amount
)

# Adding 2 seats at $10/seat with 50% time remaining
delta_amount = 2 * $10 * 0.5 = $10

BillingEntry(
    type=BillingEntryType.subscription_seats_increase,
    direction=BillingEntryDirection.debit,
    amount=1000  # cents
)

Type	Description	Grant Action
`meter_credit`	Usage allowances	Create meter_credited event
`github_repository`	Repo access	Add to GitHub team
`discord`	Server role	Assign Discord role
`license_keys`	License distribution	Generate key
`downloadables`	File access	Grant download permission
`custom`	Webhook-based	Call external URL

1. Order/Subscription created
2. enqueue_benefits_grants(task="grant")
3. For each benefit in product:
   - Skip if already granted
   - Enqueue benefit.grant task
4. benefit.grant task:
   - Get/create BenefitGrant record
   - Call strategy.grant() (type-specific)
   - Set granted_at
   - Store properties
   - Send webhook

1. Subscription canceled or order refunded
2. enqueue_benefits_grants(task="revoke")
3. For each granted benefit:
   - Enqueue benefit.revoke task
4. benefit.revoke task:
   - Call strategy.revoke() (type-specific)
   - Set revoked_at
   - Send webhook

# Create event with units
Event(type="meter_credited", units=100)
# Update CustomerMeter

# Calculate rollover
rollover = min(remaining_units, rollover_limit)
# Reset meter
Event(type="meter_reset")
# Credit new period + rollover
Event(type="meter_credited", units=base_units + rollover)

# Negative credit event
Event(type="meter_credited", units=-remaining_units)

1. order.process_dunning runs hourly
2. Finds orders where next_payment_attempt_at <= now
3. For each order:
   - Enqueue order.process_dunning_order
4. process_dunning_order:
   - Get customer's payment method
   - Attempt payment via Stripe
   - On success: mark order paid
   - On failure: schedule next attempt

payment fails → status=past_due, past_due_at=now
               ↓
         benefits may continue (grace period)
               ↓
         retry succeeds → status=active
               ↓
         retry fails → status=unpaid, benefits revoked

Type	Description
`payment`	Customer payment received
`processor_fee`	Stripe fees
`refund`	Money returned to customer
`refund_reversal`	Refund failed/reversed
`dispute`	Chargeback loss
`dispute_reversal`	Won dispute
`balance`	Internal balance transfer
`payout`	Money sent to creator

1. charge.updated webhook (charge settled)
2. Get balance_transaction from Stripe
3. Extract settlement amount and fees
4. Create Transaction(type=payment)
5. Enqueue processor_fee.create_payment_fees
6. Create Transaction(type=processor_fee)

1. Creator has balance from transactions
2. payout.trigger_stripe_payouts (daily)
3. Calculate available balance
4. Create Payout record
5. stripe_service.transfer() to Connect account
6. stripe_service.create_payout() to bank
7. payout.paid webhook → update status

server/polar/models/
├── checkout.py
├── order.py
├── order_item.py
├── subscription.py
├── subscription_product_price.py
├── transaction.py
├── payment.py
├── refund.py
├── dispute.py
├── payout.py
├── customer.py
├── product.py
├── product_price.py
├── discount.py
├── benefit.py
├── benefit_grant.py
└── billing_entry.py

server/polar/
├── subscription/service.py
├── order/service.py
├── checkout/service.py
├── payment/service.py
├── refund/service.py
├── dispute/service.py
├── payout/service.py
├── benefit/
│   ├── service.py
│   ├── grant/service.py
│   └── strategies/
│       ├── meter_credit/service.py
│       ├── github_repository/service.py
│       ├── discord/service.py
│       └── ...
└── transaction/service/
    ├── payment.py
    ├── refund.py
    └── dispute.py

server/polar/
├── subscription/tasks.py
├── order/tasks.py
├── checkout/tasks.py
├── benefit/tasks.py
├── payout/tasks.py
└── integrations/stripe/tasks.py

server/polar/integrations/stripe/
├── endpoints.py    # Webhook handlers
├── service.py      # Stripe API wrapper
├── tasks.py        # Webhook processing tasks
└── payment.py      # Payment resolution helpers

Field	Type	Description
`email`, `name`	str	Contact info
`stripe_customer_id`	str	Stripe link
`billing_address`	Address	Stored address
`tax_id`	str	For tax compliance

Task	Trigger	Action
`checkout.handle_free_success`	Free product	Complete without payment
`checkout.expire_open_checkouts`	Every 15 min	Mark expired checkouts

Behavior	Action
`prorate`	Add to next invoice
`invoice`	Create order immediately

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

Field	Type	Description
`type`	BillingEntryType	cycle, proration, metered, seats_increase, seats_decrease
`direction`	Direction	debit, credit
`amount`	int	Entry amount

Polar Billing

Polar Billing System

Quick Reference

Table of Contents

Polar Billing

Polar Billing System

Quick Reference

Table of Contents

1. Core Entities

Checkout

Order

Subscription

Transaction

Payment

Refund

Customer

Product & ProductPrice

BillingEntry

2. Entity Relationships

3. Main Services

SubscriptionService

OrderService

CheckoutService

PaymentService

RefundService

BenefitGrantService

4. Dramatiq Background Tasks

Subscription Tasks

Order Tasks

Stripe Webhook Tasks

Benefit Tasks

Checkout Tasks

Payout Tasks

5. Stripe Integration

Webhook Endpoints

Implemented Webhooks

Webhook Processing Flow

StripeService

6. Subscription Lifecycle

Creation Flow

Cycle Flow (Renewal)

Cancellation Flow

Trial Flow

7. Proration System

When Prorations Occur

Proration Calculation

Proration Behaviors

BillingEntry for Prorations

Seat Proration

8. Benefits & Credits

Benefit Types

Benefit Grant Flow

Benefit Revocation Flow

Meter Credits

Grace Period

9. Dunning & Payment Retry

Dunning Process

Retry Schedule

Subscription Status During Dunning

10. Transaction Ledger

Transaction Types

Creating Payment Transactions

Payout Flow

11. Key File Locations

Models

Services

Background Tasks

Stripe Integration

Common Debugging Scenarios

Payment Failed

Benefits Not Granted

Proration Issues

Subscription Not Cycling

Customer Billing Ops

Billing Automation

Paypal Integration

Stripe Integration

Pci Compliance

Square Automation