shield_lock
JinDaGe
← Back to skills
extension
Category: Development & EngineeringNo API key required

polar-integration

Integrate Polar payments, subscriptions, and checkout into web projects. Use when asked to add payments via Polar, set up Polar checkout, configure Polar webhooks, create Polar products, integrate Polar SDK, set up customer portal, add subscription billing with Polar, or any task involving polar.sh payment platform. Triggers on mentions of Polar payments, Polar checkout, Polar webhooks, Polar subscriptions, @polar-sh/sdk, @polar-sh/nextjs, @polar-sh/checkout.

personAuthor: jakexiaohubgithub
open_in_newRepositorydownloadDownload package

Polar Integration

Polar is a payment platform for digital products: subscriptions, one-time purchases, licenses, checkout, and webhooks. This skill provides complete integration guidance.

Integration Workflow

1. Determine the Stack

Identify the project's framework. Polar has first-class support for:

2. Install Dependencies

npm install @polar-sh/sdk
# For Next.js projects:
npm install zod @polar-sh/nextjs
# For SvelteKit projects:
npm install zod @polar-sh/sveltekit
# For Supabase projects:
npm install zod @polar-sh/supabase
# For embedded checkout:
npm install @polar-sh/checkout
# For Python projects:
pip install polar-sdk

Note: The Polar SDK is in active development. Pin versions to avoid breaking changes: npm install @polar-sh/sdk@^0.46 / pip install polar-sdk~=0.28

3. Configure Authentication

Set up environment variables:

POLAR_ACCESS_TOKEN=polar_at_xxx     # Organization Access Token from Polar dashboard
POLAR_WEBHOOK_SECRET=xxx            # Webhook signing secret

Create Organization Access Tokens from organization settings in Polar dashboard. See references/authentication.md for details.

For sandbox/testing, use server: "sandbox" in SDK config. For production, use server: "production" or omit. See references/sandbox.md for sandbox details (test cards, API URLs, limitations).

4. Set Up Checkout

Choose approach based on needs:

| Approach | When to Use | |----------|-------------| | Checkout Links | No-code, shareable URLs | | Checkout API | Programmatic control, dynamic pricing | | Embedded Checkout | Inline on your site, no redirect |

Quick start (Next.js):

// app/checkout/route.ts
import { Checkout } from "@polar-sh/nextjs";

export const GET = Checkout({
  accessToken: process.env.POLAR_ACCESS_TOKEN,
  successUrl: process.env.SUCCESS_URL,
  server: "sandbox",
});
// Use: GET /checkout?products=PRODUCT_ID

Quick start (SDK):

import { Polar } from "@polar-sh/sdk";

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

const checkout = await polar.checkouts.create({
  products: ["PRODUCT_ID"],
});
// Redirect user to checkout.url

5. Set Up Webhooks

Webhooks notify your app about payment events (order created, subscription canceled, etc.).

Quick start (Next.js):

// app/api/webhook/polar/route.ts
import { Webhooks } from "@polar-sh/nextjs";

export const POST = Webhooks({
  webhookSecret: process.env.POLAR_WEBHOOK_SECRET!,
  onPayload: async (payload) => {
    // Handle any event
  },
  onOrderCreated: async (payload) => {
    // Handle new order
  },
  onSubscriptionCreated: async (payload) => {
    // Handle new subscription
  },
});

Quick start (Express):

import express from "express";
import { validateEvent, WebhookVerificationError } from "@polar-sh/sdk/webhooks";

app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  try {
    const event = validateEvent(req.body, req.headers, process.env.POLAR_WEBHOOK_SECRET ?? "");
    // Process event
    res.status(202).send("");
  } catch (error) {
    if (error instanceof WebhookVerificationError) res.status(403).send("");
    throw error;
  }
});

For webhook setup in Polar dashboard: references/webhooks-setup.md For local development with polar listen: references/webhooks-local.md For delivery handling, retries, troubleshooting: references/webhooks-delivery.md

6. Set Up Customer Portal (Optional)

Give customers access to their orders and subscriptions.

Next.js:

// app/portal/route.ts
import { CustomerPortal } from "@polar-sh/nextjs";

export const GET = CustomerPortal({
  accessToken: process.env.POLAR_ACCESS_TOKEN,
  getCustomerId: async (req) => "CUSTOMER_ID", // resolve from your auth
  server: "sandbox",
});

SDK:

const session = await polar.customerSessions.create({ customerId: "CUSTOMER_ID" });
// Redirect to session.customerPortalUrl

See references/customer-portal.md.

Reference Index

Load these files when you need detailed information on a specific topic:

SDK & Frameworks

Authentication

Products & Pricing

Checkout

Webhooks

Benefits & License Keys

  • references/benefits.md — Benefit types (Credits, License Keys, File Downloads, GitHub, Discord, Custom), grant lifecycle, webhooks
  • references/license-keys.md — License key validation, activation/deactivation, limits, brandable prefixes

Events & Metering

Orders & Customers

Webhook Events

Metrics & Analytics

Customer State & Sandbox

API Reference

AI Integration

  • references/mcp.md — Polar MCP server for AI agents (Cursor, Claude, ChatGPT, etc.)