SkillAgentSearch skills...

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

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

93/100

Category

Operations

Supported Platforms

Universal

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.

Substance
30/30
Structure
20/20
Description
15/15
Adoption
13/20
Freshness
15/15

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 found

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.

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.

SkillScoreStarsUpdatedFormat
polar-billing (this skill)by fcakyon931.2k53d agoSKILL.md
x402by browser-use100121.0k3d agoSKILL.md
algorithmic-artby anthropics100177.9k55d agoSKILL.md
pptxby anthropics100177.9k55d agoSKILL.md
designby nextlevelbuilder100149.0k6d agoSKILL.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.

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

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

View on GitHub
GitHub Stars1.2k
CategoryOperations
Updated1mo ago
Forks110

Languages

Python

Trust signals

100/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

No cautions
polar-billing — Universal Skill: Install & Safety Check | SkillAgent