Polar

You are integrating Polar as a Merchant of Record (MoR) into a [Django / Next.js / FastAPI / Express] application.

## Key Concept: Polar is the Merchant of Record
Polar is NOT just a payment processor — it is the legal seller on record. Polar collects and remits VAT/GST/US sales tax globally, handles disputes, and controls refund decisions. You receive net payouts via Stripe Connect Express after fees and taxes. This means:
- You do NOT collect or remit sales tax/VAT/GST — Polar does
- Polar issues invoices to your customers (not you)
- Refunds flow through Polar's policy; the 4% + 40¢ transaction fee is NOT refunded on refunds
- Customer disputes are handled by Polar; $15 per dispute is deducted from your balance

## Setup
1. Create an organization at polar.sh and complete the seller onboarding survey
2. Generate credentials in Settings:
   - `POLAR_ACCESS_TOKEN` — organization access token (server-side only)
   - `POLAR_WEBHOOK_SECRET` — per-endpoint secret, base64-encoded
3. For Next.js/TypeScript: `pnpm add @polar-sh/sdk @polar-sh/nextjs`
   For Python: `pip install polar-sdk`
4. Use the sandbox environment during development (`server: 'sandbox'` in SDK calls). Complete Stripe Identity KYC before your first live payout (required for payout activation).

## Fee Modeling (Read This First)
The headline 4% + 40¢ is incomplete — always model these additives:
- +1.5% for any non-US card (Stripe international pass-through)
- +0.5% for subscription payments
- $15 per dispute (non-refundable)
- Refunds lose the full transaction fee (Polar does not refund it)
Build a weighted effective-rate model based on your actual international mix and subscription ratio before committing pricing.

## Recommended Integration: Next.js Route Handlers
The cleanest pattern uses Polar's Next.js helpers for both checkout and webhooks:

```typescript
// app/api/checkout/route.ts
import { Checkout } from '@polar-sh/nextjs';

export const GET = Checkout({
  accessToken: process.env.POLAR_ACCESS_TOKEN!,
  successUrl: 'https://your-app.com/confirmation?checkout_id={CHECKOUT_ID}',
  server: process.env.NODE_ENV === 'production' ? 'production' : 'sandbox',
});
```

Link to checkout with product IDs: `/api/checkout?products=prod_xxx&[email protected]`

## Server-Side: Create Products and Prices
Use the SDK to manage products via the API or dashboard:

```typescript
import { Polar } from '@polar-sh/sdk';

const polar = new Polar({
  accessToken: process.env.POLAR_ACCESS_TOKEN!,
  server: 'sandbox',
});

// Create a product with a recurring price
const product = await polar.products.create({
  name: 'Pro Plan',
  recurringInterval: 'month',
  prices: [{
    amountType: 'fixed',
    priceAmount: 2000, // cents — $20.00
    priceCurrency: 'usd',
  }],
});
```

## Webhook Handling (Critical)
Never trust client-side checkout success alone — always confirm via webhooks.

1. In the Polar dashboard, create a webhook endpoint pointing to `https://your-app.com/api/webhooks/polar`
2. Subscribe to key events: `order.created`, `subscription.created`, `subscription.updated`, `subscription.canceled`, `customer.state_changed`, `checkout.updated`
3. Use the SDK's built-in verification:

```typescript
// app/api/webhooks/polar/route.ts
import { Webhooks } from '@polar-sh/nextjs';

export const POST = Webhooks({
  webhookSecret: process.env.POLAR_WEBHOOK_SECRET!,
  onOrderCreated: async (payload) => {
    const order = payload.data;
    // Fulfill order — use order.metadata to link to your internal records
  },
  onSubscriptionCreated: async (payload) => {
    const subscription = payload.data;
    // Grant entitlements in your app
  },
  onSubscriptionCanceled: async (payload) => {
    // Revoke entitlements
  },
  onCustomerStateChanged: async (payload) => {
    // Sync active benefits/entitlements to your user record
  },
});
```

For Python/Django, manual verification per the Standard Webhooks spec:

```python
import base64
import hashlib
import hmac

def verify_polar_webhook(request, secret: str) -> bool:
    # Polar uses Standard Webhooks headers
    webhook_id = request.headers.get('webhook-id', '')
    webhook_timestamp = request.headers.get('webhook-timestamp', '')
    webhook_signature = request.headers.get('webhook-signature', '')

    raw_body = request.body.decode('utf-8')
    signed_payload = f'{webhook_id}.{webhook_timestamp}.{raw_body}'

    # Secret is base64-encoded — decode before HMAC
    decoded_secret = base64.b64decode(secret.split('_')[-1] if '_' in secret else secret)
    expected = base64.b64encode(
        hmac.new(decoded_secret, signed_payload.encode(), hashlib.sha256).digest()
    ).decode()

    # Header format: 'v1,<base64sig> v1,<base64sig>' — check any match
    for sig in webhook_signature.split(' '):
        if sig.startswith('v1,') and hmac.compare_digest(sig[3:], expected):
            return True
    return False
```

4. CRITICAL: Do NOT parse or modify the raw request body before verification — any transformation breaks the signature
5. Deduplicate by `webhook-id` header — Standard Webhooks allows redelivery
6. Respond 200 quickly; process heavy work asynchronously

## Benefits & Entitlements
Polar's entitlements engine automatically grants/revokes benefits based on subscription state:
- **License keys** — auto-issued on purchase, with expiration, activation, device/IP limits, usage quotas
- **File downloads** — secure signed URLs
- **GitHub repo access** — auto-invites to private repos
- **Discord roles** — auto-assigned; revoked on cancellation
- **Custom benefits** — via webhooks and your own logic

Subscribe to `customer.state_changed` to mirror the full entitlement state into your database.

## Usage-Based Billing
For AI tokens, API calls, or other metered usage:

```typescript
// Ingest events via the Events API
await polar.events.ingest({
  events: [{
    name: 'ai_usage',
    externalCustomerId: 'user_123',
    metadata: { tokens: 1500, model: 'gpt-4' },
  }],
});
```

Define meters in the dashboard to aggregate events into billable units, then attach metered prices to products.

## Security Best Practices
- Never handle raw card data — Polar/Stripe handles all PCI-sensitive operations; your PCI scope is SAQ-A
- Always verify webhook signatures via the SDK (or Standard Webhooks spec manually)
- Store `metadata` references (your internal user/order IDs) when creating checkouts to link Polar records back to your database
- Use sandbox (server: 'sandbox') for all development; production Stripe Identity KYC is required before first live payout
- Monitor chargeback rate against Polar's strict 0.4% threshold — stricter than card-network defaults

## Testing
- Sandbox environment: set `server: 'sandbox'` in SDK; use Stripe test cards
- Use ngrok or a tunnel for local webhook testing
- Test full subscription lifecycle: created → active → past_due → canceled → expired
- Verify entitlement grant/revoke by checking `customer.state_changed` payloads
- Smoke-test production with a low-dollar live transaction — sandbox/production behavior occasionally diverges

## Common Gotchas
- Amounts use the smallest currency unit as integers (cents) — `2000` = $20.00
- Refunds do NOT return the 4% + 40¢ transaction fee — model this into your refund policy
- Subscription +0.5% and international +1.5% surcharges stack — an international sub is 6% + 40¢, not 4% + 40¢
- Dispute fee ($15) is deducted regardless of outcome — non-refundable even if you win
- The webhook secret is base64-encoded; the SDK handles this, but manual implementations must decode before HMAC
- Account reviews pause payouts; keep a cash buffer and respond to Polar comms within 48 hours
- No PayPal, Apple Pay Cash, or crypto — cards plus Stripe local methods only
- Customer portal is hosted by Polar; you cannot fully customize the portal UI (embed-only)