6. Connect Polar to Convex

Polar.sh handles recurring subscriptions — monthly/yearly billing, upgrades, cancellations, and customer self-service. YeetCode uses it for international (USD) subscription plans.

If you only need one-time ZAR payments for South African customers, you can skip this and use Yoco only.

Prerequisites

A Polar.sh account and organization
Your Convex backend running (bun run dev from apps/convex-backend)

1. Create Products on Polar

Log in to Polar.sh → your organization
Go to Products → Create Product
Create a product for each tier you want (e.g., Free, Pro, Enterprise)
Copy each product's Product ID — you'll need these for config.yaml

2. Get Your API Credentials

In Polar, go to Settings → Developers
Create a Personal Access Token with the scopes you need
Copy the token (starts with polar_pat_...)

3. Register the Webhook Endpoint

Run the setup script to register your Convex backend as a webhook receiver:

npx convex run --no-push polar/init:registerWebhookEndpoint

This will:

Connect to the Polar API
Register (or update) a webhook at https://your-convex-url.convex.site/webhook-events/polar
Subscribe to events: checkout.updated, order.created, subscription.created, subscription.updated, subscription.revoked
Return the webhook secret for signature verification

If a webhook already exists for your Convex URL, the script updates it to include all required events.

Save the webhook secret — you'll need it in the next step.

4. Set Environment Variables

In the Convex Dashboard, go to Settings → Environment Variables and add:

Variable	Value	Description
`POLAR_ACCESS_TOKEN`	`polar_pat_...`	Your Polar personal access token
`POLAR_ENVIRONMENT`	`sandbox` or `production`	Use `sandbox` for development
`POLAR_WEBHOOK_SECRET`	The secret from step 3	Standard Webhooks signature verification
`POLAR_DISCOUNT_TRIGGER_PRODUCT_ID`	Product ID	Which product purchase triggers a discount code
`POLAR_DISCOUNT_PRODUCT_ID`	Product ID	Which product the discount code applies to

The discount variables are optional — they power the auto-generated discount code workflow. If you don't need discount codes, set them to any placeholder value.

5. Configure Pricing Tiers

Edit config.yaml at the repo root to define your subscription plans:

pricing:
  - id: "free"
    name: "Free"
    icon: "package"
    description: "Get started for free."
    highlighted: false
    price: 0
    currency: "$"
    priceLabel: "/month"
    features:
      - "Feature one"
      - "Feature two"
      - "Community support"
    cta: "Get Started"
    polarProductId: "your-polar-product-id-here"
    rank: 1
  - id: "pro"
    name: "Pro"
    icon: "rocket"
    description: "For serious builders."
    highlighted: true
    badge: "Most Popular"
    price: 29
    currency: "$"
    priceLabel: "/month"
    features:
      - "Everything in Free"
      - "Pro features"
      - "Priority support"
    cta: "Start Free Trial"
    polarProductId: "your-polar-product-id-here"
    rank: 2

Replace polarProductId values with the real product IDs from step 1. The rank field determines tier hierarchy — higher rank includes all lower tiers.

After editing, run bun run dev or bun run config:generate to regenerate the typed config.

6. Verify the Integration

Start the dev server: bun run dev
Visit your marketing site's pricing section
Click a plan to start checkout
Complete a test purchase using Polar's sandbox mode
Check the Convex Dashboard → Data tab:
- A subscriptions record should appear with status: "active"
- An orders record should appear
- A webhooks record should appear with provider: "polar"
Check that the confirmation email was sent (check Resend dashboard or email inbox)

What Happens After Setup

Once connected, these flows run automatically:

Customer subscribes → Polar hosts checkout, handles payment
Webhooks fire → Your Convex backend receives subscription lifecycle events
Subscription tracked → Status changes (active, canceled, past_due, revoked) are reflected in the subscriptions table
Emails sent → Confirmation on subscribe, notification on cancel (via Resend)
Customer portal → Customers can manage their subscription through Polar's hosted portal
Discount codes → When a customer buys the trigger product, a 100% off discount code is auto-generated and emailed (configurable)

Next Steps

Polar Pricing & Subscriptions — in-depth guide on subscription management, customer portal, and discount workflows
Payments Overview — comparison of Polar vs Yoco and when to use each

6. Connect Polar to Convex

On this page