setup-polar

Polar Setup Wizard

Interactive setup guide to get Polar payments working in your project.

Setup Flow

Follow these steps in order:

Step 1: Check MCP Availability

First, check if the Polar MCP server is available by listing organizations: call execute with GET /v1/organizations/, or organizations_list where the server exposes one tool per operation.

If MCP tools work: Skip to Step 3.

If MCP not available: Continue to Step 2.

Step 2: Install Polar MCP

Polar plugin installed: the plugin already configures the Polar server (polar, plus polar-sandbox where available). Ask the user to sign in to it, preferring polar-sandbox: in Claude Code with /mcp, in Codex with codex mcp login <server>, in Cursor or Antigravity from their MCP settings, in Gemini CLI with /mcp auth <server>, and in ChatGPT when prompted to connect. Then continue with the verification below.

Otherwise, guide the user to install the Polar MCP server based on their environment:

Claude Code:

# Production
claude mcp add --transport http polar https://mcp.polar.sh/mcp/polar-mcp

# Sandbox (recommended for setup)
claude mcp add --transport http polar-sandbox https://mcp.polar.sh/mcp/polar-sandbox

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "polar-sandbox": {
      "url": "https://mcp.polar.sh/mcp/polar-sandbox"
    }
  }
}

For other clients, follow the Polar MCP guide. After installing, the user restarts their editor or CLI and signs in when prompted (in Claude Code, run /mcp and authenticate). The sandbox server signs in at sandbox.polar.sh and the production server at polar.sh.

Once authenticated, verify MCP works by listing organizations.

Step 3: Gather Project Context

Ask the user:

1. Framework: What framework are you using?

   • Next.js (App Router), Express, Hono, Astro, SvelteKit, Remix, TanStack Start, Nuxt, Fastify, Cloudflare Workers, or another TypeScript/JavaScript framework
   • Python: there's no integration skill; follow the Python SDK docs

2. Environment: Start with sandbox or production?

   • Sandbox (recommended for new setups)
   • Production

3. Product type: What are you selling?

   • Subscription (recurring)
   • One-time purchase
   • Both

From here on, use the polar-sandbox server's tools for sandbox and the polar server's tools for production. If only polar is available (as in ChatGPT), create sandbox products in the sandbox dashboard or with the Polar CLI instead.

Step 4: Choose the Organization

List the organizations with MCP. If there are several, ask which one to use. Note its id, slug and default_presentment_currency. Signing in to the MCP server already asks a user without an organization to create one; without MCP, they can create one at:

• Sandbox: https://sandbox.polar.sh/start
• Production: https://polar.sh/start

Step 5: Create First Product

Create the product with MCP (POST /v1/products/). The price must be in the organization's default_presentment_currency, and the billing interval is fixed per product. Example for a monthly subscription:

{
  "organization_id": "<organization id from Step 4>",
  "name": "Pro Plan",
  "recurring_interval": "month",
  "prices": [{ "amount_type": "fixed", "price_amount": 2900, "price_currency": "<default_presentment_currency>" }]
}

Omit recurring_interval for a one-time purchase. "Both", or monthly and yearly billing, means separate products. Show the user the server, organization, name, price, currency and interval, and create the product once they confirm.

Store the returned product ID for checkout integration.

Step 6: Generate Integration Code

Hand off to the polar-integration skill to generate the Checkout, Customer Portal, and Webhooks endpoints for the framework selected in Step 3. That skill has the canonical, framework-agnostic recipes plus per-framework variations.

Before invoking it, make sure the user has these environment variables ready (use whatever loader their framework provides):

POLAR_ACCESS_TOKEN=          # organization access token, created below
POLAR_WEBHOOK_SECRET=        # created in Step 7
POLAR_ENVIRONMENT=sandbox    # omit or set to "production" when going live

The quickest way to create the access token is the Polar CLI. Install it with npm install -g @polar-sh/cli, then ask the user to run:

polar auth login --sandbox
token=$(polar auth token --scope checkouts:write --scope customer_sessions:write) && echo "POLAR_ACCESS_TOKEN=$token" >> .env

polar auth token opens the token page in a browser with those scopes preselected, waits for the user to create the token, and prints it, so this saves it to .env without showing it. The token belongs to the active organization and its environment: polar auth whoami --json shows which one that is, and polar auth org changes it.

Without the CLI, create the token in the sandbox or production dashboard: Settings → Access Tokens → Create token.

Pass along the product ID from Step 5 so checkout links can be tested in Step 8.

Step 7: Set Up Webhooks

Start the dev server, then follow polar-testing ("Local Webhook Testing") to forward webhooks to it with the Polar CLI. It needs no tunnel and no dashboard endpoint:

1. If you skipped it in Step 6, install the CLI and ask the user to run polar auth login --sandbox, which opens a browser.
2. Save the local signing secret to .env with polar webhook listen --print-secret, then restart the dev server.
3. Start polar webhook listen <port>/<webhook-path> in the background, using the path from the route generated in Step 6. Pass --org <id from Step 4> if the account has several organizations.
4. Run polar webhook trigger order.paid. Success is exit 0 with a Response 2xx line. On a failure it prints the handler's response and exits with status 1; fix the handler and repeat. If it only says the event was forwarded by your polar webhook listen terminal, check the listen output.

When deploying, create a webhook endpoint for the public URL in the dashboard (Settings → Webhooks) or with MCP (url, format: "raw" and the events: order.paid, subscription.created and subscription.canceled). Use that endpoint's secret as POLAR_WEBHOOK_SECRET in the deployed environment. The MCP response contains the secret, so tell the user where to copy it rather than repeating it.

Step 8: Test the Integration

1. Visit the checkout URL with the product ID from Step 5 (path and query shape come from the route generated in Step 6).
2. Complete checkout using test card: 4242 4242 4242 4242.
3. Verify that polar webhook listen shows order.paid with a 2xx status from the handler.
4. Check the success page displays correctly.

Step 9: Next Steps

Once basic setup works, suggest:

1. Link to your auth - Pass external_customer_id from the logged-in user when creating checkouts.
2. Add benefits - License keys, file downloads, Discord roles.
3. Go production - Production is separate from sandbox: set up the organization at polar.sh, re-create the product (it gets a new ID), create a production access token and webhook endpoint, and set POLAR_ENVIRONMENT=production. Then submit the organization for review in the dashboard; checkouts are blocked until it can accept payments.