010113 Polar Integration

Polar.sh Payment Integration

Overview

Polar.sh is a Merchant of Record (MoR) platform that handles payment processing, tax collection, and billing. This skill covers the full integration flow: product synchronization, checkout sessions, webhook handling, database schema, and sandbox testing.

Architecture

Products DB → Sync Service → Polar API (Products/Variants/Prices)
                                       ↓
Client → Checkout Session → Polar Hosted Flow → Order Created
                                       ↓
Polar → Webhook → Application → Update Payment Status → Fulfillment

Quick Reference

Environment Variables

• POLAR_ACCESS_TOKEN — Server-side API token (format: polar_oat_*)
• POLAR_WEBHOOK_SECRET — Webhook signature verification
• NEXT_PUBLIC_POLAR_SANDBOX — Toggle sandbox/production (true or omitted)

Core Flows

1. Sync products to Polar before checkout — each product+variant+currency becomes a Polar product
2. Create checkout session with line items and metadata — Polar handles the hosted payment UI
3. Handle webhooks for order lifecycle events (order.paid, checkout.expired, etc.)
4. Verify signatures using Standard Webhooks spec — @polar-sh/nextjs handles this automatically

Supported Countries

Polar supports 50+ countries including US, EU, UK, Canada, Australia, Brazil, Mexico, Colombia, Peru, Chile, and others. See Payment Flow for MoR model details.

References

• Payment Flow — Product sync, checkout, multi-currency, error handling, MoR model, localization
• Webhooks & Schema — Webhook events, DB schema, repository patterns, signature verification
• API Reference — Polar REST API essentials (auth, products, checkout, orders)
• Sandbox & Setup — Sandbox environment, API keys, webhook configuration
• Code Examples — Sync, checkout, webhook, cancel, raw API calls