Polar BillingSAFE

Battle-tested Claude Code, OpenAI Codex, Cursor configs, plugins, hooks and agents with Kimi, MiniMax and GLM API support.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

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

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (3)

.claude/output-styles/adhd-explanatory.md

AGENTS.md

GEMINI.md

Gates applied: no_behavioural_pass.