# 010113 Polar Integration

> Polar.sh payment integration — product sync, checkout, webhooks, multi-currency, MoR model, sandbox testing, and API reference.

- Skill: `natuleadan/010113-polar-integration` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add natuleadan/010113-polar-integration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/natuleadan/010113-polar-integration/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: natuleadan (https://skillmd.com/u/natuleadan)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/natuleadan/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