polar-billing
This skill should be used when working on Polar billing system, Stripe integration, subscription lifecycle, checkout flows, or benefit provisioning.
Install / Use
npx skills add fcakyon/claude-codex-settings --skill polar-billingInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
OperationsSupported Platforms
Tags
Our assessment of polar-billing
polar-billing scores 93/100 on our quality scale, 184th of 745 Operations skills we index (top 25%).
Its SKILL.md is 23 KB long, well organised into 94 sections with 30 code examples: a thorough specification that gives an agent plenty to work with.
With 1,153 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so polar-billing is actively maintained.
- Our last check on 2026-10-26 found the source still online.
- It is released under the Apache-2.0 license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-10-04. Automated pattern scan on 2026-10-04. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
polar-billing compared with similar skills
All 4 of these similar skills score higher than polar-billing; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| polar-billing (this skill)by fcakyon | 93 | 1.2k | 53d ago | SKILL.md |
| x402by browser-use | 100 | 121.0k | 3d ago | SKILL.md |
| algorithmic-artby anthropics | 100 | 177.9k | 55d ago | SKILL.md |
| pptxby anthropics | 100 | 177.9k | 55d ago | SKILL.md |
| designby nextlevelbuilder | 100 | 149.0k | 6d ago | SKILL.md |
Frequently asked questions
- How do I install polar-billing?
- Run
npx skills add fcakyon/claude-codex-settings --skill polar-billing. The install tabs above show the steps for each supported agent. - Which AI agents does polar-billing work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is polar-billing safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is Apache-2.0-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is polar-billing still maintained?
- The repository was last updated about 2 months ago, so polar-billing is actively maintained.
Skill content
View source on GitHubname: 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
- Core Entities
- Entity Relationships
- Main Services
- Dramatiq Background Tasks
- Stripe Integration
- Subscription Lifecycle
- Proration System
- Benefits & Credits
- Dunning & Payment Retry
- Transaction Ledger
- 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 - discounttotal_amount= net + taxdue_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 invoices (falls back to name) |
| stripe_customer_id | str | Stripe link |
| billing_address | Address | Stored address |
| tax_id | str | For tax compliance |
Product & ProductPrice
Files: server/polar/models/product.py, server/polar/models/product_price.py
| ProductPrice Types | Description |
|-------------------|-------------|
| ProductPriceFixed | Fixed amount (set price_amount=0 for free) |
| ProductPriceCustom | Merchant sets at checkout |
| ProductPriceMeteredUnit | Pay-per-unit |
| ProductPriceSeatUnit | Per-seat with tiers |
BillingEntry
File: server/polar/models/billing_entry.py
Audit log for billing calculations.
| Field | Type | Description |
|-------|------|-------------|
| type | BillingEntryType | cycle, proration, metered, seats_increase, seats_decrease |
| direction | Direction | debit, credit |
| amount | int | Entry amount |
2. Entity Relationships
Organization
├── Product
│ ├── ProductPrice (multiple per product)
│ └── ProductBenefit → Benefit
├── Customer
│ ├── Subscription → Organization, 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, discount=None)
update_seats(subscription, seats, proration_behavior)
update_discount(subscription, discount) # discount: UUID | Literal["unset"]
update_trial(subscription, trial_end)
update_metadata(subscription, metadata)
# 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)
# Also enqueues chargeback prevention notice for dispute_prevention refunds
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
| 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 billable subscriptions (trialing, active, past_due) |
Order Tasks
File: server/polar/order/tasks.py
| 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 |
Stripe Webhook Tasks
File: server/polar/integrations/stripe/tasks.py
| 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 |
Benefit Tasks
File: server/polar/benefit/tasks.py
| 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 |
Checkout Tasks
File: server/polar/checkout/tasks.py
| Task | Trigger | Action |
|------|---------|--------|
| checkout.handle_free_success | Free product | Complete without payment |
| checkout.expire_open_checkouts | Every 15 min | Mark expired checkouts |
Payout Tasks
File: server/polar/payout/tasks.py
| Task | Trigger | Action | |------|---------|--------| | `payout.trigger_stripe_pay
Truncated for display — read the full file on GitHub.
Related Skills
x402
121.0kSet up Browser Use Cloud payments with x402 — pay per request from a crypto wallet (USDC on Base mainnet), no signup or API key.
algorithmic-art
177.9kCreating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems.
pptx
177.9kUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an em…
design
149.0kComprehensive design skill: brand identity, design tokens, UI styling, logo generation (55 styles, Gemini, Atlas Cloud, or MuAPI AI), corporate identity program (50 deliverables, CIP mockups), HTML presentations (Chart.js), banner design (22 styles, social/ads/web/print), icon design (15 styles, SVG…
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
