polar-integration

Polar Integration

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 ダッシュボードの組織設定から、Organization Access Token を作成します。詳しくは references/authentication.md を参照してください。

サンドボックス／テストでは、SDK の設定で server: "sandbox" を使用します。本番環境では server: "production" を使用するか、省略します。サンドボックスの詳細（テストカード、API URL、制限事項）については、references/sandbox.md を参照してください。

4. チェックアウトを設定する

ニーズに応じて方法を選択します。

方法	使用する状況
Checkout Links	コード不要で、共有可能な URL
Checkout API	プログラムによる制御、動的な価格設定
Embedded Checkout	リダイレクトせず、サイト内にインライン表示

• Checkout Links：references/checkout-links.md
• Checkout API：references/checkout-api.md
• Embedded Checkout：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 — 特典の種類（クレジット、ライセンスキー、ファイルのダウンロード、GitHub、Discord、カスタム）、付与のライフサイクル、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 エージェント（Cursor、Claude、ChatGPT など）向け Polar MCP サーバー