english/.opencode/skills/payment-integration/references/polar/overview.md

Polar Overview

Comprehensive payment & billing platform for software monetization with Merchant of Record services.

Core Capabilities

Platform Features:

• Digital product sales (one-time, recurring, usage-based)
• Merchant of Record - handles global tax compliance
• Subscription lifecycle management
• Automated benefit distribution
• Customer self-service portal
• Real-time webhook system
• Analytics dashboard
• Multi-language SDKs

Merchant of Record Benefits:

• Global tax compliance (VAT, GST, sales tax)
• Tax calculations for all jurisdictions
• B2B reverse charge, B2C tax collection
• Invoicing from Polar to customers
• Payout invoicing to merchants
• Transparent fees (20% discount vs other MoRs)

Authentication

Organization Access Tokens (OAT)

For: Server-side API access

Create:

1. Org Settings → Developers
2. Create new access token
3. Copy and store securely

Usage:

Authorization: Bearer polar_xxxxxxxxxxxxxxxx

Security: Never expose client-side (auto-revoked if leaked)

OAuth 2.0

For: Third-party app integration

Authorization URL: https://polar.sh/oauth2/authorize Token URL: https://api.polar.sh/v1/oauth2/token

Flow:

1. Redirect to authorize URL with scopes
2. User approves permissions
3. Receive authorization code
4. Exchange code for access_token + refresh_token
5. Use access_token for API calls

Scopes:

• products:read/write - Product management
• checkouts:read/write - Checkout operations
• orders:read - View orders
• subscriptions:read/write - Subscription management
• benefits:read/write - Benefit configuration
• customers:read/write - Customer management
• discounts:read/write - Discount codes
• refunds:read/write - Refund processing

Customer Sessions

For: Customer-facing portal operations

Create: Server-side API call returns customer access token Usage: Pre-authenticated customer portal links Scope: Restricted to customer-specific operations

Base URLs

Production:

• Dashboard: https://polar.sh
• API: https://api.polar.sh/v1/

Sandbox:

• Dashboard: https://sandbox.polar.sh
• API: https://sandbox-api.polar.sh/v1/

SDK Configuration:

const polar = new Polar({
  accessToken: process.env.POLAR_ACCESS_TOKEN,
  server: "production" // or "sandbox"
});

Rate Limits

Limits:

• 300 requests/minute per org/customer/OAuth2 client
• 3 requests/second for unauthenticated license validation

Response: HTTP 429 with Retry-After header

Handling:

if (response.status === 429) {
  const retryAfter = response.headers.get('Retry-After');
  await sleep(retryAfter * 1000);
  return retry();
}

Key Concepts

External Customer ID

• Map your user IDs to Polar customers
• Set at checkout: external_customer_id
• Query API by external_id
• Immutable once set
• Use for all customer operations

Metadata

• Custom key-value storage
• Available on products, customers, subscriptions, orders
• For reporting and filtering
• Not indexed, use for supplementary data

Billing Reasons

Track order types via billing_reason:

• purchase - One-time product
• subscription_create - New subscription
• subscription_cycle - Renewal invoice
• subscription_update - Plan change

Environments

Sandbox:

• Separate account required
• Separate organization
• Separate access tokens (production tokens don't work)
• Test with Stripe test cards

Test Cards (Stripe):

• Success: 4242 4242 4242 4242
• Decline: 4000 0000 0000 0002
• Auth Required: 4000 0025 0000 3155
• Expiry: Any future date
• CVC: Any 3 digits

SDKs

Official SDKs:

• TypeScript/JavaScript: @polar-sh/sdk
• Python: polar-sdk
• PHP: polar-sh/sdk
• Go: Official SDK

Framework Adapters:

• Next.js: @polar-sh/nextjs (quickstart: npx polar-init)
• Laravel: polar-sh/laravel
• Remix, Astro, Express, TanStack Start
• Elysia, Fastify, Hono, SvelteKit

BetterAuth Integration:

• Package: @polar-sh/better-auth
• Auto-create customers on signup
• External ID mapping
• User-customer sync

Support & Resources

• Docs: https://polar.sh/docs
• API Reference: https://polar.sh/docs/api-reference
• LLMs.txt: https://polar.sh/docs/llms.txt
• GitHub: https://github.com/polarsource/polar
• Discussions: https://github.com/orgs/polarsource/discussions

Next Steps

• For products: Load products.md
• For checkout: Load checkouts.md
• For subscriptions: Load subscriptions.md
• For webhooks: Load webhooks.md
• For benefits: Load benefits.md
• For SDK usage: Load sdk.md