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](references/payment-flow.md) for MoR model details.

References

• [Payment Flow](references/payment-flow.md) — Product sync, checkout, multi-currency, error handling, MoR model, localization
• [Webhooks & Schema](references/webhooks-schema.md) — Webhook events, DB schema, repository patterns, signature verification
• [API Reference](references/api-reference.md) — Polar REST API essentials (auth, products, checkout, orders)
• [Sandbox & Setup](references/sandbox-setup.md) — Sandbox environment, API keys, webhook configuration
• [Code Examples](references/code-examples.md) — Sync, checkout, webhook, cancel, raw API calls

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: natuleadan
• Source: natuleadan/skills
• License: MIT
• Homepage: https://www.skills.sh/natuleadan/skills

Install and usage instructions live in the source repository linked above.