Polar Setup (Payments)

Before you start this guide: You must have completed 06 — Vercel Setup so you have your permanent vercel.app domain.

Polar is the payment processor that charges your customer's credit card and handles subscriptions. It takes less than 5 minutes to connect.

Create a Polar Account

• 1.1 Go to https://polar.sh

• 1.2 Click Sign in with GitHub or create an account.

• 1.3 Polar will ask you to create an "Organization". Name it after your business.

• 1.4 Look at the Polar sidebar on the left. Click Products.

• 1.5 Click the "Create Product" button.

Create the Subscription Products

You need to create two items for people to buy: A "Starter" plan and a "Pro" plan.

• 2.1 In the Create Product window:

• Name: Starter Tier

• Pricing: Recurring (Subscription)

• Amount: $49.00 a month (or whatever you want to charge)

• Click Create Product.

• 2.2 As soon as you create it, Polar will show you a unique "Product ID" at the top of the next screen (it looks like a long string of random numbers/letters).

• Copy this Product ID.

• Open your .env file in VS Code.

• Add a new line for it:

POLAR_PRODUCT_ID=your-copied-id

• 2.3 Now, let's create a checkout link so customers can actually buy it.
• In the Polar sidebar, click Checkout Links.
• Click the New (+) icon in the top right.
• Label: ShipClawFast Checkout
• Product: Select the "$49.00 Starter Tier" product you just made.
• Success URL: https://www.your-vercel-domain.com/dashboard/success?session_id={CHECKOUT_ID} (Change your-vercel-domain to your real Vercel domain!)
• Return URL: https://www.your-vercel-domain.com/dashboard/success
• Allow Discounts: Toggle this ON (very important for testing).
• Click Create Link.

(Note: Without a checkout link, a customer cannot subscribe, which means Fly.io won't know to create their AI machine!)

• 2.4 Let's make a 100% off discount code so you can test the checkout flow yourself without paying real money.
• In the Polar sidebar, click Discounts.
• Click New Discount.
• Name: Testing
• Code: TESTING100 or something you like
• Type: Percentage (100%)
• Duration: Once
• Restrictions: Select your Starter Tier product.
• Max Redemptions: 5 (Allows you to test it 5 times without error).
• Click Create.

Note: Make sure to delete discounts once you are live.

Set up the Webhook

When a customer pays, Polar needs to "call" your backend on the internet to tell it to give the customer an AI agent. This is called a Webhook.

• 3.1 In the Polar sidebar on the left, click Developers.

• 3.2 Click Webhooks, then click the "Add Endpoint" button.

• 3.3 You will see a box asking for the Endpoint URL. This is where we need to tell Polar where your backend API will live.

• Even though we haven't built the API yet, we are going to reserve its name right now!

• Pick a name for your API (like mybusiness-api).

• Type exactly this format into the Polar Endpoint URL box: https://[YOUR_API_NAME].fly.dev/billing/webhook

(Example: https://shipclawfast-api.fly.dev/billing/webhook)

[CRITICAL WARNING] Your webhook URL MUST end exactly with /billing/webhook. If it ends in anything else, or if you misspell your .fly.dev domain, Polar will throw a 404 Not Found or [Errno -2] DNS error, and your customers' AI Machines will never spin up!

• 3.4 Check the box next to checkout.created, order.created, order.paid, subscription.created, subscription.updated, subscription.canceled, subscription.active, and subscription.revoked to tell it to listen for payment events. Click Create Endpoint.

• 3.5 Polar will instantly generate a Webhook Secret (a very long, hidden password). Click the button to reveal it and copy it.

• 3.6 Go back to your .env file in VS Code and add the secret:

POLAR_WEBHOOK_SECRET=your-secret...

Get your Final Key

The last thing we need is the master access token so your backend can verify receipts.

• 4.1 While still on the Developers page in Polar, click Access Tokens.

• 4.2 Click Create Token. Name it whatever you want (e.g. "Server Token") and click Create.

• 4.3 Copy the token. (It will start with polar_oat_...).

• 4.4 Go back to your .env file and add it:

POLAR_ACCESS_TOKEN=polar_oat_...

Checklist — Before moving on

Your .env file in VS Code should now be looking very full!

[... your Supabase keys from earlier ...]
[... your Google key from earlier ...]
[... your WEB_URL from earlier ...]
POLAR_STARTER_PRICE_ID=d1298...
POLAR_PRO_PRICE_ID=a55bc...
POLAR_WEBHOOK_SECRET=whsec_abc123...
POLAR_ACCESS_TOKEN=polar_oat_m8z...

• I created two Products and pasted their IDs into the .env file
• I saved my future Fly SDK name in Polar's Webhook URL ending in exactly /billing/webhook
• I pasted the Webhook secret and the Access Token into the .env file

When every checkbox above is ticked, move on to 08 — Fly.io Setup.