Skills
skills/bbssppllvv/essential-skills/polar-integration

polar-integration

SKILL.md

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

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.)
Weekly Installs
5
Repository
bbssppllvv/esse…l-skills
GitHub Stars
1
First Seen
Feb 28, 2026
Security Audits
Gen Agent Trust HubPass
SocketFail
SnykWarn
Installed on
gemini-cli5
opencode5
codebuddy5
github-copilot5
codex5
kimi-cli5