Polar integration

opensaas-sh/blog/src/content/docs/guides/deploying.mdx

@@ -199,6 +199,20 @@ With the webhook url ready, go to your [Lemon Squeezy Webhooks Dashboard](https:
   - subscription_cancelled
 - click `save`
 
+### Setting up your Production Polar Webhook
+
+To set up your Polar webhook, you'll need the URL of your newly deployed server + `/payments-webhook`, e.g. `https://open-saas-wasp-sh-server.fly.dev/payments-webhook`. 
+
+With the webhook URL ready, go to `Settings` > `Webhooks` in your [Polar Dashboard](https://polar.sh/dashboard):
+- click the `Add Endpoint` button.
+- paste the webhook forwarding URL in the `URL` field.
+- set the `Format` to `"Raw"`
+- select at least the following events to be sent:
+  - order.paid
+  - subscription.updated
+- click `Save`
+- copy the generated webhook secret (a long, random string starting with `polar_whs_`).
+- add this signing secret to your server's production environment variables under `POLAR_WEBHOOK_SECRET=`
 
 ## Deploying your Blog
 

opensaas-sh/blog/src/content/docs/guides/payments-integration.mdx

@@ -16,43 +16,67 @@ import variantId from '@assets/lemon-squeezy/variant-id.png';
 import subscriptionVariantIds from '@assets/lemon-squeezy/subscription-variant-ids.png';
 import ngrok from '@assets/lemon-squeezy/ngrok.png';
 import storeId from '@assets/lemon-squeezy/store-id.png';
+import addPolarProduct from '@assets/polar/add-product.png';
+import addPolarToken from '@assets/polar/add-token.png';
+import polarUserTable from '@assets/polar/user-table.png';
+import polarWebhookLogs from '@assets/polar/webhook-log.png';
 
 This guide will show you how to set up Payments for testing and local development with the following payment processors:
 - Stripe
 - Lemon Squeezy
+- Polar
 
 :::note[Which should I choose?]
 Stripe is the industry standard, is more configurable, and has cheaper fees.
-Lemon Squeezy acts a [Merchant of Record](https://www.lemonsqueezy.com/reporting/merchant-of-record). This means they take care of paying taxes in multiple countries for you, but charge higher fees per transaction. 
+Lemon Squeezy acts a [Merchant of Record](https://www.lemonsqueezy.com/reporting/merchant-of-record). This means they take care of paying taxes in multiple countries for you, but charge higher fees per transaction.
+Polar is an open-source [Merchant of Record](https://docs.polar.sh/merchant-of-record/introduction#merchant-of-record) designed specifically for developers.
 :::
 
 ## Important First Steps
 
-First, go to `/src/payment/paymentProcessor.ts` and choose which payment processor you'd like to use, e.g. Stripe or Lemon Squeezy:
+First, go to `/src/payment/paymentProcessor.ts` and choose which payment processor you'd like to use, e.g. Stripe, Lemon Squeezy, or Polar:
 
-```ts title="src/payment/paymentProcessor.ts" ins={5, 7}
+```ts title="src/payment/paymentProcessor.ts" ins={6, 8, 10}
 import { stripePaymentProcessor } from './stripe/paymentProcessor';
 import { lemonSqueezyPaymentProcessor } from './lemonSqueezy/paymentProcessor';
+import { polarPaymentProcessor } from './polar/paymentProcessor';
 //...
 
 export const paymentProcessor: PaymentProcessor = stripePaymentProcessor;
 // or... 
 export const paymentProcessor: PaymentProcessor = lemonSqueezyPaymentProcessor;
+// or...
+export const paymentProcessor: PaymentProcessor = polarPaymentProcessor;
 ```
 
 At this point, you can delete:
 - the unused payment processor code within the `/src/payment/<unused-provider>` directory, 
 - any unused environment variables from `.env.server` (they will be prefixed with the name of the provider your are not using):
-  - e.g. `STRIPE_API_KEY`, `STRIPE_CUSTOMER_PORTAL_URL`, `LEMONSQUEEZY_API_KEY`, `LEMONSQUEEZY_WEBHOOK_SECRET`
+  - e.g. `STRIPE_API_KEY`, `LEMONSQUEEZY_API_KEY`, `POLAR_ACCESS_TOKEN`
 - Make sure to also uninstall the unused dependencies:
-  - `npm uninstall @lemonsqueezy/lemonsqueezy.js`
-  - or
-  - `npm uninstall stripe`
+  - If using Stripe
+    ```sh
+    npm uninstall @lemonsqueezy/lemonsqueezy.js @polar-sh/sdk
+    ```
+  - If using Lemon Squeezy
+    ```sh
+    npm uninstall stripe @polar-sh/sdk
+    ```
+  - If using Polar
+    ```sh
+    npm uninstall @lemonsqueezy/lemonsqueezy.js stripe
+    ```
 - Remove any unused fields from the `User` model in the `schema.prisma` file if they exist:
   - e.g. `lemonSqueezyCustomerPortalUrl`
 
 Now your code is ready to go with your preferred payment processor and it's time to configure your payment processor's API keys, products, and other settings.
 
+Follow the steps for your selected processor:
+
+- [Stripe](#stripe)
+- [Lemon Squeezy](#lemon-squeezy)
+- [Polar](#polar)
+
 ## Stripe
 
 First, you'll need to create a Stripe account. You can do that [here](https://dashboard.stripe.com/register).
@@ -306,6 +330,128 @@ Now go to your [Lemon Squeezy Webhooks Dashboard](https://app.lemonsqueezy.com/s
 
 You're now ready to start consuming Lemon Squeezy webhook events in local development.
 
+## Polar
+
+First, make sure you've defined your payment processor in `src/payment/paymentProcessor.ts`, as described in the [important first steps](#important-first-steps).
+
+Next, you'll need to create a Polar account. You can do that [here](https://polar.sh).
+
+:::tip[Star our Repo on GitHub! 🌟]
+We've packed in a ton of features and love into this SaaS starter, and offer it all to you for free!
+
+If you're finding this template and its guides useful, consider giving us [a star on GitHub](https://github.com/wasp-lang/wasp)
+:::
+
+### Enable Sandbox Mode
+
+For local development and testing, you'll want to use Polar's sandbox mode. The Polar sandbox is fully isolated, so there are separate URLs for the [sandbox dashboard](https://sandbox.polar.sh/dashboard) and [live dashboard](https://polar.sh/dashboard), each with independent products, sales, access tokens, etc. 
+
+Add the following to your `.env.server` file:
+
+```ts title=".env.server"
+POLAR_SANDBOX_MODE=true
+```
+
+:::note[Going Live]
+When you're ready to go live, change this to `false`.
+:::
+
+### Get your Polar API Access Token
+
+Once you've created your account, you'll need to get your API access token. You can do that by navigating to the `Developers` section under your dashboard settings and creating a new personal access token.
+
+- Click on the `New Token` button to create a new token
+- Give your token a name (e.g., "Open SaaS Development")
+- Copy the generated token and paste it in your `.env.server` file, e.g. `POLAR_ACCESS_TOKEN=polar_oat_...`
+
+### Create Test Products
+
+To create test products in Polar, go to the `Products` section in your Polar dashboard.
+
+- Click on the `New Product` button to create a new product
+- Fill in the product details:
+  - **Name**: e.g., "Hobby Plan", "Pro Plan", or "10 Credits"
+  - **Description**: Brief description of what the product includes
+  - **Pricing**: Select "Monthly" or "Yearly" for recurring plans or "One-time purchase" for credits, then configure the desired pricing type
+- Configure any remaining optional fields, e.g. **Media**, **Checkout Fields**, **Metadata**, etc
+- Click `Create Product`
+
+After creating each product, you'll need to copy the Product ID from the product page and add it to your `.env.server` file:
+
+```ini title=".env.server"
+PAYMENTS_HOBBY_SUBSCRIPTION_PLAN_ID=<your-hobby-product-id>
+PAYMENTS_PRO_SUBSCRIPTION_PLAN_ID=<your-pro-product-id>
+PAYMENTS_CREDITS_10_PLAN_ID=<your-credits-product-id>
+```
+
+:::note[Product ID Location]
+The Product ID can be acquired on the product page in your Polar dashboard. Tap the `⠇` icon in the top-right corner, then select `Copy Product ID`.
+:::
+
+### Create and Use the Polar Webhook in Local Development
+
+Polar notifies your Wasp app through a webhook (for example, when a payment succeeds). During development, you need to expose your locally running Wasp server (started with `wasp start`) to the internet. Because the Wasp server runs on port 3001 by default, run `ngrok` on the same port. `ngrok` will generate a public URL that you can give to Polar.
+
+To do this, first make sure you have installed [`ngrok`](https://ngrok.com/docs/getting-started/).
+
+Once `ngrok` is installed and your Wasp app is running, run:
+
+```sh
+ngrok http 3001
+```
+
+<Image src={ngrok} alt="ngrok" loading="lazy" />
+
+`ngrok` will display a forwarding address. Copy this address and append `/payments-webhook` to it. This path is already configured in `main.wasp` under the `api paymentsWebhook` definition. It should look something like this: 
+
+```sh title="Callback URL"
+https://89e5-2003-c7-153c-72a5-f837.ngrok-free.app/payments-webhook
+```
+
+Next, configure the webhook in your Polar dashboard:
+
+- Go to `Webhooks` page under `Settings`
+- Click `Add Endpoint` to create a new endpoint
+- In the URL field, paste your `ngrok` forwarding address with `/payments-webhook` appended (for example: `https://abc123.ngrok-free.app/payments-webhook`).
+- Set the `Format` to `"Raw"`
+- Select the following events to listen for:
+  - `order.paid`
+  - `subscription.updated`
+- Click `Save`
+- Copy the generated webhook secret and add it to your `.env.server` file:
+
+```ini title=".env.server"
+POLAR_WEBHOOK_SECRET=polar_whs_...
+```
+
+### Testing Payments via the Local Application
+
+Make sure that your **`ngrok` tunnel is running** and that the webhook is configured as described above.
+
+You can then test the payment flow:
+
+- Click a Buy button for any product on the homepage
+- You should be redirected to Polar's checkout page
+- Fill in the checkout form with [test payment information](https://docs.polar.sh/integrate/sandbox#testing-payments)
+- Complete the payment
+- You should be redirected back to your success page
+
+Check the Polar dashboard for webhook event logs and verify the user's subscription status in your database:
+
+<Image src={polarWebhookLogs} alt="How to check webhook logs in Polar dashboard" loading="lazy" />
+
+```sh
+wasp db studio
+```
+
+Navigate to `localhost:5555` and check the `User` table to confirm the `subscriptionStatus` is `active` for the user who made the purchase.
+
+<Image src={polarUserTable} alt="User table showing updated user" loading="lazy" />
+
+:::note[Polar Test Cards]
+Polar uses Stripe's test card numbers for development. Check their [testing documentation](https://docs.stripe.com/testing#cards) for further information.
+:::
+
 ## Deploying
 
-Once you deploy your app, you can follow the same steps, just make sure that you are no longer in test mode within the Stripe or Lemon Squeezy Dashboards. After you've repeated the steps in live mode, add the new API keys and price/variant IDs to your environment variables in your deployed environment.
+Once you deploy your app, you can follow the same steps, just make sure that you are no longer in test/sandbox mode within the Stripe, Lemon Squeezy, or Polar dashboards. After you've repeated the steps in live mode, add the new API keys and price/variant IDs to your environment variables in your deployed environment.

opensaas-sh/blog/src/content/docs/start/guided-tour.md

@@ -186,19 +186,19 @@ For development purposes, Wasp provides a `Dummy` email sender which Open SaaS c
 
 We will explain more about these auth methods, and how to properly integrate them into your app, in the [Authentication Guide](/guides/authentication/).
 
-### Subscription Payments with Stripe or Lemon Squeezy
+### Subscription Payments with Stripe, Lemon Squeezy or Polar
 
-No SaaS is complete without payments, specifically subscription payments. That's why this template comes with a fully functional Stripe or Lemon Squeezy integration. 
+No SaaS is complete without payments, specifically subscription payments. That's why this template comes with a fully functional Stripe, Lemon Squeezy or Polar integration. 
 
 Let's take a quick look at how payments are handled in this template.
 
 1. a user clicks the `BUY` button and a **Checkout session** is created on the server
 2. the user is redirected to the Checkout page where they enter their payment info
 3. the user is redirected back to the app and the Checkout session is completed
-4. Stripe / Lemon Squeezy sends a webhook event to the server with the payment info
+4. Stripe / Lemon Squeezy / Polar sends a webhook event to the server with the payment info
 5. The app server's **webhook handler** handles the event and updates the user's subscription status
 
-The payment processor you choose (Stripe or Lemon Squeezy) and its related functions can be found at `src/payment/paymentProcessor.ts`. The `Payment Processor` object holds the logic for creating checkout sessions, webhooks, etc.
+The payment processor you choose (Stripe, Lemon Squeezy or Polar) and its related functions can be found at `src/payment/paymentProcessor.ts`. The `Payment Processor` object holds the logic for creating checkout sessions, webhooks, etc.
 
 The logic for creating the Checkout session is defined in the `src/payment/operation.ts` file. [Actions](https://wasp.sh/docs/data-model/operations/actions) are a type of Wasp Operation, specifically your server-side functions that are used to **write** or **update** data to the database. Once they're defined in the `main.wasp` file, you can easily call them on the client-side:
 
@@ -226,7 +226,7 @@ const handleBuyClick = async (paymentPlanId) => {
 };
 ```
 
-The webhook handler is defined in the `src/payment/webhook.ts` file. Unlike Actions and Queries in Wasp which are only to be used internally, we define the webhook handler in the `main.wasp` file as an API endpoint in order to expose it externally to Stripe
+The webhook handler is defined in the `src/payment/webhook.ts` file. Unlike Actions and Queries in Wasp which are only to be used internally, we define the webhook handler in the `main.wasp` file as an API endpoint in order to expose it externally to the payment processor.
 
 ```js title="main.wasp"
 api paymentsWebhook {
@@ -277,7 +277,7 @@ For more info on integrating Plausible or Google Analytics, check out the [Analy
 When you first start your Open SaaS app straight from the template, it will run, but many of the services won't work because they lack your own API keys. Here are list of services that need your API keys to work properly:
 
 - Auth Methods (Google, GitHub)
-- Stripe or Lemon Squeezy
+- Stripe, Lemon Squeezy or Polar
 - OpenAI (Chat GPT API)
 - Email Sending (Sendgrid) -- you must set this up if you're using the `email` Auth method 
 - Analytics (Plausible or Google Analytics)

template/app/.env.server.example

@@ -17,6 +17,15 @@ LEMONSQUEEZY_STORE_ID=012345
 # define your own webhook secret when creating a new webhook on https://app.lemonsqueezy.com/settings/webhooks
 LEMONSQUEEZY_WEBHOOK_SECRET=my-webhook-secret
 
+# After creating an organization, you can find your organization id in the organization settings https://sandbox.polar.sh/dashboard/[your org slug]/settings
+POLAR_ORGANIZATION_ID=00000000-0000-0000-0000-000000000000
+# Generate a token at https://sandbox.polar.sh/dashboard/[your org slug]/settings
+POLAR_ACCESS_TOKEN=polar_oat_...
+# Define your own webhook secret when creating a new webhook at https://sandbox.polar.sh/dashboard/[your org slug]/settings/webhooks
+POLAR_WEBHOOK_SECRET=polar_whs_...
+# For production, set this to false, then generate a new organization and products from the live dashboard
+POLAR_SANDBOX_MODE=true
+
 # If using Stripe, go to https://dashboard.stripe.com/test/products and click on + Add Product
 # If using Lemon Squeezy, go to https://app.lemonsqueezy.com/products and create new products and variants
 PAYMENTS_HOBBY_SUBSCRIPTION_PLAN_ID=012345

template/app/package.json

@@ -9,6 +9,8 @@
     "@headlessui/react": "1.7.13",
     "@hookform/resolvers": "^5.1.1",
     "@lemonsqueezy/lemonsqueezy.js": "^3.2.0",
+    "@polar-sh/express": "^0.3.2",
+    "@polar-sh/sdk": "^0.34.3",
     "@radix-ui/react-accordion": "^1.2.11",
     "@radix-ui/react-avatar": "^1.1.10",
     "@radix-ui/react-checkbox": "^1.3.2",

template/app/src/analytics/stats.ts

@@ -8,8 +8,11 @@ import {
   getSources,
 } from "./providers/plausibleAnalyticsUtils";
 // import { getDailyPageViews, getSources } from './providers/googleAnalyticsUtils';
+import { OrderStatus } from "@polar-sh/sdk/models/components/orderstatus.js";
 import { paymentProcessor } from "../payment/paymentProcessor";
 import { SubscriptionStatus } from "../payment/plans";
+import { polarClient } from "../payment/polar/polarClient";
+import { assertUnreachable } from "../shared/utils";
 
 export type DailyStatsProps = {
   dailyStats?: DailyStats;
@@ -60,10 +63,11 @@ export const calculateDailyStats: DailyStatsJob<never, void> = async (
       case "lemonsqueezy":
         totalRevenue = await fetchTotalLemonSqueezyRevenue();
         break;
+      case "polar":
+        totalRevenue = await fetchTotalPolarRevenue();
+        break;
       default:
-        throw new Error(
-          `Unsupported payment processor: ${paymentProcessor.id}`,
-        );
+        assertUnreachable(paymentProcessor.id);
     }
 
     const { totalViews, prevDayViewsChangePercent } = await getDailyPageViews();
@@ -211,3 +215,24 @@ async function fetchTotalLemonSqueezyRevenue() {
     throw error;
   }
 }
+
+async function fetchTotalPolarRevenue(): Promise<number> {
+  let totalRevenue = 0;
+
+  const result = await polarClient.orders.list({
+    limit: 100,
+  });
+
+  for await (const page of result) {
+    const orders = page.result.items || [];
+
+    for (const order of orders) {
+      if (order.status === OrderStatus.Paid && order.totalAmount > 0) {
+        totalRevenue += order.totalAmount;
+      }
+    }
+  }
+
+  // Revenue is in cents so we convert to dollars
+  return totalRevenue / 100;
+}

template/app/src/payment/PricingPage.tsx

@@ -125,9 +125,9 @@ const PricingPage = () => {
           </h2>
         </div>
         <p className="text-muted-foreground mx-auto mt-6 max-w-2xl text-center text-lg leading-8">
-          Choose between Stripe and LemonSqueezy as your payment provider. Just
-          add your Product IDs! Try it out below with test credit card number{" "}
-          <br />
+          Choose between Stripe, LemonSqueezy or Polar as your payment provider.
+          Just add your Product IDs! Try it out below with test credit card
+          number <br />
           <span className="bg-muted text-muted-foreground rounded-md px-2 py-1 font-mono text-sm">
             4242 4242 4242 4242 4242
           </span>

template/app/src/payment/paymentProcessor.ts

@@ -16,7 +16,7 @@ export interface FetchCustomerPortalUrlArgs {
 }
 
 export interface PaymentProcessor {
-  id: "stripe" | "lemonsqueezy";
+  id: "stripe" | "lemonsqueezy" | "polar";
   createCheckoutSession: (
     args: CreateCheckoutSessionArgs,
   ) => Promise<{ session: { id: string; url: string } }>;
@@ -32,4 +32,5 @@ export interface PaymentProcessor {
  * other payment processor code that you're not using  from `/src/payment`
  */
 // export const paymentProcessor: PaymentProcessor = lemonSqueezyPaymentProcessor;
+// export const paymentProcessor: PaymentProcessor = polarPaymentProcessor;
 export const paymentProcessor: PaymentProcessor = stripePaymentProcessor;