polar-billing

What it does

Guides an agent to operate on Polar's billing infrastructure, covering Stripe integration, checkout flows, subscriptions, proration, and benefits provisioning. It outlines entities, relationships, services, background tasks, and Stripe interactions.

How it works

• Describes core entities: Checkout, CheckoutLink, Order, Subscription, Transaction, Payment, Refund, Customer, Product & ProductPrice, BillingEntry.
• Details relationships among Organization, Product, Customer, Subscription, Order, Payment, Discount, and Account depending on ledger flows.
• Lists Main Services with concrete functions and signatures:
  • SubscriptionService: create_or_update_from_checkout(checkout, payment_method), update_product(...), update_seats(...), update_discount(...), update_trial(...), cycle(...), cancel(...), revoke(...), uncancel(...), enqueue_benefits_grants(...).
  • OrderService: create_from_checkout(checkout), create_subscription_order(subscription, billing_reason), trigger_payment(order), create_order_balance(order).
  • CheckoutService: create(product, customer_data, discount_code), confirm(checkout), handle_stripe_success(checkout, charge), handle_free_success(checkout).
  • PaymentService: upsert_from_stripe_charge(charge, checkout, order), handle_success(payment), handle_failure(payment).
  • RefundService: create(order, amount, reason, revoke_benefits), upsert_from_stripe(stripe_refund).
  • BenefitGrantService: enqueue_benefits_grants(task, customer, product, order=None, subscription=None), grant_benefit(customer, benefit), revoke_benefit(customer, benefit).
• Outlines Dramatiq background tasks across Subscription, Order, Stripe Webhook, Benefit, Checkout, Payout, Refund with specific task names and triggers.
• Details Stripe integration including webhook endpoints, implemented events, and a processing flow from Stripe to external events, storage, and asynchronous processing.
• Enumerates StripeService key methods: create_payment_intent(), create_setup_intent(), create_refund(), get_refund(), create_tax_calculation(), create_tax_transaction(), transfer(), create_payout().
• Provides Subscription lifecycle flows: Creation, Cycle/Renewal, Cancellation, Trial, including statuses and actions like benefit grants, email, and ledger entries.
• Covers Proration System: triggers when product changes or seat changes.

When to use it

Use when working on Polar billing system, Stripe integration, subscription lifecycle, checkout flows, or benefit provisioning.

What it can touch

• Functions and classes referenced under server/polar/... including models (Checkout, CheckoutLink, Order, Subscription, Transaction, Payment, Refund, Customer), services (subscription, order, checkout, payment, refund, benefit), and Stripe integration modules.
• Background tasks and Stripe webhook handlers as described (Dramatiq tasks and Stripe endpoints).

Caveats

• License: Apache-2.0.
• Describes procedural steps and concrete function signatures as explicit in the skill, with no extrapolated outcomes beyond listed flows.