polar-integration

Polar 集成

Polar 是一个面向数字产品的支付平台，支持订阅、一次性购买、许可证、结账和 Webhook。本技能提供完整的集成指南。

集成工作流

1. 确定技术栈

确定项目使用的框架。Polar 为以下框架提供一流支持：

• Next.js，使用 @polar-sh/nextjs — 参见 references/nextjs.md
• SvelteKit，使用 @polar-sh/sveltekit — 参见 references/sveltekit.md
• Supabase，使用 @polar-sh/supabase — 参见 references/supabase.md
• 任意 JS/TS 框架，使用 @polar-sh/sdk — 参见 references/typescript-sdk.md
• Python，使用 polar-sdk — 参见 references/python-sdk.md
• 其他框架适配器：Astro、Express、Hono、Fastify、Remix、Nuxt、Elysia、Deno、TanStack Start、Better Auth

2. 安装依赖

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

注意： Polar SDK 正在积极开发中。请锁定版本以避免不兼容变更： npm install @polar-sh/sdk@^0.46 / pip install polar-sdk~=0.28

3. 配置身份验证

设置环境变量：

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

在 Polar 控制面板的组织设置中创建组织访问令牌。详情请参见 references/authentication.md。

对于沙盒/测试，在 SDK 配置中使用 server: "sandbox"。对于生产环境，使用 server: "production" 或省略该项。沙盒详情（测试卡、API URL、限制）请参见 references/sandbox.md。

4. 设置结账

根据需求选择方式：

方式	使用场景
结账链接	无需代码，可分享 URL
结账 API	以编程方式控制、动态定价
嵌入式结账	在网站内嵌显示，无需重定向

• 结账链接：references/checkout-links.md
• 结账 API：references/checkout-api.md
• 嵌入式结账：references/checkout-embedded.md

快速入门（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

快速入门（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. 设置 Webhook

Webhook 会将支付事件（创建订单、取消订阅等）通知你的应用。

快速入门（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
  },
});

快速入门（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;
  }
});

在 Polar 控制面板中设置 Webhook：references/webhooks-setup.md 使用 polar listen 进行本地开发：references/webhooks-local.md 有关投递处理、重试和故障排除：references/webhooks-delivery.md

6. 设置客户门户（可选）

让客户访问他们的订单和订阅。

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

参见 references/customer-portal.md。

参考索引

需要了解特定主题的详细信息时，请加载以下文件：

SDK 和框架

• references/typescript-sdk.md — TS/JS SDK 安装、快速入门、框架适配器列表
• references/python-sdk.md — Python SDK 安装、同步/异步用法、沙盒配置
• references/nextjs.md — 用于结账、门户和 Webhook 的 Next.js 路由处理程序，以及所有 Webhook 处理程序名称
• references/sveltekit.md — 使用 @polar-sh/sveltekit 集成 SvelteKit、文件路径和示例
• references/supabase.md — 使用 @polar-sh/supabase 集成 Supabase Edge Functions

身份验证

• references/authentication.md — OAT 令牌、安全性、GitHub 密钥扫描
• references/oauth2.md — OAuth 2.0 流程、授权码交换、PKCE、组织令牌与用户令牌

产品与定价

• references/products.md — 创建产品、定价模式、计费周期、权益、变体、归档
• references/trials.md — 免费试用期、防止滥用、管理现有订阅的试用
• references/seat-based-pricing.md — 团队/B2B 定价、席位管理、认领流程、API 示例
• references/discounts.md — 百分比/固定金额折扣、代码、限制、定期选项
• references/custom-fields.md — 自定义结账字段（文本、数字、日期、复选框、选择）

结账

• references/checkout-links.md — 无代码结账链接、查询参数、UTM 跟踪
• references/checkout-api.md — 以编程方式创建结账会话、临时价格、多种产品
• references/checkout-embedded.md — 嵌入式结账、JS 库、React 集成、事件、钱包支付

Webhook

• references/webhooks-setup.md — 创建端点、传递格式、密钥、事件订阅
• references/webhooks-local.md — 使用 Polar CLI 进行本地开发（polar listen）
• references/webhooks-delivery.md — 验证、SDK 示例、IP 允许列表、重试逻辑、故障排除

权益与许可证密钥

• references/benefits.md — 权益类型（Credits、License Keys、File Downloads、GitHub、Discord、Custom）、授予生命周期、Webhook
• references/license-keys.md — 许可证密钥验证、激活/停用、限制、可自定义品牌的前缀

事件与计量

• references/events-metering.md — 按用量计费、事件接收、计量器、成本跟踪、额度

订单与客户

• references/orders-subscriptions.md — 销售概览、结账状态、付款尝试
• references/customer-portal.md — 客户门户 URL、通过 API 获取经过身份验证的链接
• references/refunds.md — 退款处理、Webhook 事件、撤销权益

Webhook 事件

• references/webhook-events.md — 所有 Webhook 事件的完整列表、框架处理程序名称

指标与分析

• references/metrics.md — 收入、MRR、流失率、转化率、AOV、成本洞察

客户状态与沙盒

• references/customer-state.md — 一次 API 调用即可获取客户的订阅、权益、计量器；customer.state_changed Webhook
• references/sandbox.md — 沙盒环境、测试卡号、API URL、SDK 配置、限制

API 参考

• references/api-reference.md — 所有 API 端点的完整列表、速率限制、分页、作用域

AI 集成

• references/mcp.md — 面向 AI Agent（Cursor、Claude、ChatGPT 等）的 Polar MCP 服务