Set up Polar with an AI agent

name: Polar
description: Use when building billing infrastructure for digital products,
  managing subscriptions, processing payments, handling usage-based billing,
  automating customer benefits, or integrating checkout flows into applications.
  Polar is a Merchant of Record platform that handles tax compliance, payment
  processing, and customer management globally.
metadata:
  mintlify-proj: polar
  version: "1.0"

Polar Skill

Product Summary

Polar is a complete billing and payments platform for digital products. It acts as your Merchant of Record, handling tax compliance globally, subscription management, one-time purchases, usage-based billing, and automated customer benefits (license keys, file downloads, GitHub/Discord access, etc.). Use the REST API with TypeScript/Python SDKs, CLI for local development and testing, or no-code Checkout Links for quick integration. Primary docs: https://polar.sh/docs. Current API version: 2026-10 (use this unless you need new features in 2027-01).

Key files and commands:

• Organization Access Token (OAT): Create in dashboard Settings → API Keys
• CLI: polar auth login, polar webhook, polar products, polar subscriptions
• SDKs: @polar-sh/sdk (TypeScript), polar (Python)
• API base: https://api.polar.sh/v1 (production) or https://sandbox-api.polar.sh/v1 (sandbox)
• Webhook secret: Generated when creating webhook endpoint; use to verify incoming events

When to Use

Reach for this skill when:

• Building checkout flows for digital products (SaaS, courses, templates, software)
• Managing recurring subscriptions with automatic renewals and dunning
• Implementing usage-based billing (charge per API call, token, GB, etc.)
• Automating customer benefits (license keys, GitHub repo access, Discord roles, file downloads)
• Handling international tax compliance (VAT, GST, sales tax)
• Creating customer portals or self-service subscription management
• Setting up webhook handlers to sync orders, subscriptions, and customer events
• Testing billing flows locally before production
• Migrating from another payment processor

Quick Reference

Authentication

Method	Use Case	Where to Create
Organization Access Token (OAT)	Server-side API calls, admin operations	Dashboard → Settings → API Keys
Customer Session Token	Client-side customer portal access	/v1/customer-sessions/ endpoint (server-side)
OAuth 2.0	Third-party apps acting on behalf of users	For partner integrations only

Product Types

Type	Billing	Use Case
One-time purchase	Charge once, lifetime access	Digital products, courses, templates
Subscription	Recurring (daily/weekly/monthly/yearly)	SaaS, memberships, recurring services
Metered (usage-based)	Charge per unit consumed	API calls, tokens, storage, bandwidth
Seat-based	Per-seat pricing with volume tiers	Team plans, multi-user licenses

Pricing Models

Model	Description	Example
Fixed price	Set amount, customer pays that	$99/month
Pay-what-you-want	Customer chooses, with optional minimum	Minimum $10, default $29
Free	No charge, useful for lead magnets	Free tier with benefits
Metered	Charge based on usage + optional base fee	$10/month + $0.01 per API call

CLI Commands

# Authentication
polar auth login                    # Sign in via browser
polar auth whoami                   # Show active organization
polar auth org                      # Switch organization
polar auth token                    # Create/print access token

# Webhooks (local development)
polar webhook                       # Forward webhooks to localhost
polar webhook trigger               # Send sample event to handler

# Resources
polar products list                 # List all products
polar subscriptions list            # List all subscriptions
polar customers list                # List all customers
polar orders list                   # List all orders
polar meters list                   # List usage meters

Common API Endpoints

Operation	Endpoint	Method
Create checkout session	POST /v1/checkouts/	POST
Get checkout session	GET /v1/checkouts/{id}	GET
Create product	POST /v1/products/	POST
List products	GET /v1/products/	GET
Create subscription	POST /v1/subscriptions/	POST
Update subscription	PATCH /v1/subscriptions/{id}	PATCH
Create customer session	POST /v1/customer-sessions/	POST
Ingest usage events	POST /v1/events/ingest	POST
Create webhook endpoint	POST /v1/webhooks/endpoints	POST

Webhook Events (Common)

• checkout.created, checkout.updated, checkout.expired
• order.created, order.paid, order.refunded
• subscription.created, subscription.active, subscription.cycled, subscription.canceled
• customer.created, customer.updated, customer.deleted
• benefit_grant.created, benefit_grant.cycled, benefit_grant.revoked

Decision Guidance

When to Use Checkout Links vs. Checkout API

Scenario	Use Checkout Links	Use Checkout API
Share a static URL (email, social media, website button)	✓
Prefill customer data from your backend		✓
Dynamically compute price or products per user		✓
Apply discount programmatically		✓
Embed checkout in your app		✓
Quick no-code setup	✓

When to Use Core API vs. Customer Portal API

Task	Core API (OAT)	Customer Portal API (Session Token)
Create/update products	✓
Issue refunds	✓
Manage all customers	✓
Customer views own subscriptions		✓
Customer cancels own subscription		✓
Customer updates payment method		✓
Admin dashboards	✓
Customer self-service portal		✓

When to Use Metered Pricing vs. Seat-Based

Scenario	Metered	Seat-Based
Charge per API call, token, or GB	✓
Charge per team member		✓
Usage varies unpredictably	✓
Fixed number of users per plan		✓
Overage charges	✓
Volume discounts on seats		✓

Workflow

1. Set Up Products

1. Sign in to Polar dashboard
2. Create a product: choose pricing model (fixed, pay-what-you-want, metered, seat-based)
3. Set billing cycle (one-time or recurring interval)
4. Add benefits (license keys, file downloads, GitHub access, Discord roles, etc.)
5. Configure checkout fields if you need custom data from customers
6. Note the product ID for API calls

2. Create Checkout Flow

Option A: No-code (Checkout Links)

1. Go to Checkout Links in dashboard
2. Select products, optional discount, success/return URLs
3. Copy the link, share anywhere
4. Each visit creates a new checkout session

Option B: Programmatic (Checkout API)

1. Get organization access token
2. Call POST /v1/checkouts/ with product IDs, customer data, metadata
3. Receive checkout URL and session ID
4. Redirect customer to checkout URL or embed in iframe
5. On success, customer is redirected to success_url with checkout_id query param

3. Handle Webhooks

1. Create webhook endpoint: Dashboard → Settings → Webhooks → Add Endpoint
2. Provide endpoint URL (must be publicly accessible)
3. Select events to subscribe to (e.g., order.paid, subscription.cycled)
4. Copy webhook secret
5. In your handler, verify signature using SDK or manual HMAC verification
6. Parse event payload and sync to your database
7. Return 200 to acknowledge receipt (Polar retries on failure)

Local testing:

polar webhook                    # Forwards webhooks to localhost
polar webhook trigger order.paid # Send sample event

4. Implement Usage-Based Billing (if needed)

1. Create a meter: Dashboard → Products → Meters → New Meter
2. Define what to measure (e.g., "api_calls", filter on event name, sum a field)
3. Create metered price on product: link to meter, set per-unit rate
4. From your app, ingest events: POST /v1/events/ingest with customer_id, event name, metadata
5. Polar aggregates usage and invoices at billing cycle end (or meter cycle if set separately)

5. Verify Integration

• Checkout session creates successfully with test product
• Webhook endpoint receives events (test with polar webhook trigger)
• Webhook signature verifies correctly
• Order/subscription data syncs to your database
• Customer portal session token works and restricts to customer's data
• Sandbox environment isolated from production
• API version pinned (use 2026-10 unless you need 2027-01 features)

Common Gotchas

• Billing cycle and pricing type are immutable: Once set on a product, you cannot change them. Create a new product if you need different billing or pricing model.
• Existing subscribers grandfathered on old price: Changing a fixed price only affects new purchases. Use the API to migrate individual subscribers if needed.
• Metadata key limits: Max 40 characters per key, 500 per value, 50 pairs total. Plan your metadata structure.
• Webhook secrets rotate: Store the secret securely; if leaked, regenerate it immediately. Polar auto-revokes tokens detected in public repos.
• Customer IP address for currency detection: If creating checkout sessions server-side, pass customer_ip_address so Polar detects the right currency. Otherwise it uses your server's IP.
• Sandbox is fully isolated: Tokens, organizations, and data in sandbox don't affect production. Create separate tokens for each environment.
• Don't test with real cards: Use Stripe test card numbers in sandbox. Real card testing triggers account reviews and can block your account.
• Proration behavior: When a subscription price changes mid-cycle, proration reconciles the difference. Set default at org level or per API call.
• Trial period overrides: Trial set on Checkout Link overrides product's default trial, but only for that link.
• Benefit grants are automatic: Add a benefit to a product and existing customers get it immediately. Remove it and they lose access.
• Usage meter balance is your responsibility: Polar never blocks a customer based on meter balance. You must check and enforce limits in your app.
• Webhook delivery is not guaranteed once: Implement idempotency (check if event already processed) and handle retries gracefully.
• API versioning: New features go to "Next" version first. Current version is frozen. Deprecated version is removed after 9 months.

Verification Checklist

Before submitting work:

• Product created with correct pricing model and billing cycle
• Checkout session or link generates without errors
• Webhook endpoint URL is publicly accessible and returns 200
• Webhook secret stored securely (not in code)
• Webhook signature verification implemented (use SDK if available)
• Test event received and parsed correctly
• Order/subscription data synced to your database
• Customer portal session token restricts to authenticated customer only
• Metadata attached to checkout/order/subscription as expected
• Sandbox environment used for testing (not production)
• API version pinned in code (2026-10 or 2027-01)
• Organization Access Token never exposed in client-side code
• Proration behavior set (default or explicit per call)
• Benefit grants tested (add/remove benefit, verify customer access)
• Error handling covers 4xx and 5xx responses
• Idempotency implemented for webhook handlers

Resources

Comprehensive navigation: https://polar.sh/docs/llms.txt

Critical pages:

1. API Reference (Current Version 2026-10) — Authentication, endpoints, request/response schemas
2. Checkout Session API — Programmatic checkout creation with all options
3. Webhooks & Events — Event types, delivery, verification, and subscription renewal flow

---

For additional documentation and navigation, see: https://polar.sh/docs/llms.txt