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.

Safety Notice

This listing is imported from skills.sh public index metadata. Review upstream SKILL.md and repository scripts before running.

Copy this and send it to your AI assistant to learn

Install skill "polar-integration" with this command: npx skills add bbssppllvv/essential-skills/bbssppllvv-essential-skills-polar-integration

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:

ApproachWhen to Use
Checkout LinksNo-code, shareable URLs
Checkout APIProgrammatic control, dynamic pricing
Embedded CheckoutInline 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.)

Source Transparency

This detail page is rendered from real SKILL.md content. Trust labels are metadata-based hints, not a safety guarantee.

Open in GitHubOpen in ClawHub

Related Skills

Related by shared tags or category signals.

General

product-design

No summary provided by upstream source.

Repository SourceNeeds Review
-7
bbssppllvv
General

soniox

No summary provided by upstream source.

Repository SourceNeeds Review
-6
bbssppllvv
General

openrouter

No summary provided by upstream source.

Repository SourceNeeds Review
-5
bbssppllvv