polar-billing

Polar renews subscriptions via an APScheduler-triggered subscription.cycle task at period end. It advances period dates, creates a BillingEntry, enqueues order creation with billing_reason=subscription_cycle, then triggers Stripe payment and ledger entries on success.

Polar receives Stripe events at /v1/integrations/stripe/webhook endpoints, verifies signatures, stores them in an external_events table, and processes them asynchronously via Dramatiq tasks for charges, refunds, disputes, and payouts.

Polar calculates proration by crediting unused time on the old price and debiting the remaining time on the new price. Depending on the proration behavior, the net amount is added to the next invoice or billed immediately, recorded as BillingEntry rows.

Failed payments set the subscription to past_due and schedule retries via the hourly order.process_dunning task based on next_payment_attempt_at. If retries exhaust, the subscription becomes unpaid and benefits are revoked, unless a grace period applies.

Benefits are granted after order or subscription creation through enqueue_benefits_grants, which queues per-benefit tasks like GitHub access, Discord roles, or meter credits. Cancellation or refunds enqueue revocation tasks that call each benefit type's revoke strategy.