Polar

Get the access token

After you have created your account for Polar and created your store, you will need to get the API key. Under the Settings, scroll to Developers and click New token. Enter a name for the token, set the expiration duration and select the scopes you want the token to have. To keep it simple, you can select all scopes.

Copy the token and save it in a secure location. You will not be able to access it after you leave the page.

Create products

For your users to choose from the available subscription plans or one-time purchases, you need to create those in the Products tab of the Polar dashboard. You can create as many products as you want, but you will need to create at least one product for the integration to work.

Create one product per plan you want to offer. If you want to offer differnt billing intervals or currencies, create a new product for each.

Create a webhook

To sync the current subscription status and other information to your database, you need to set up a webhook.

The webhook code comes ready to use with supastarter, you just have to create the webhook under Settings > Webhooks in the Polar dashboard.

Enter a name for the webhook and select at least the following events:

• order.created
• subscription.created
• subscription.updated
• subscription.canceled

To get the URL for the webhook, you can either use a local development URL or the URL of your deployed app:

Local development

If you want to test the webhook locally, you can use ngrok to create a tunnel to your local machine. Ngrok will then give you a URL that you can use to test the webhook locally.

To do so, install ngrok and run it with the following command (while your supastarter development server is running):

ngrok http 3000

This will give you a URL (see the Forwarding output) that you can use to create a webhook in Stripe. Just use that url and add /api/webhooks/payments to it.

Production / preview deployment

When you have already deployed a version of your project, you can use the actual URL to create the webhook with. This will be necessary for a production version your app later anyway.

Make sure you have a deployed version that has the POLAR_WEBHOOK_SECRET environment variable set.

Then you can use the URL of your deployed app and add /api/webhooks/payments to it.

Example URL: https://your-app.com/api/webhooks/payments

After creating the webhook, you will get a webhook secret. Copy this secret and save it in a secure location. You will not be able to access it after you leave the page.

Add environment variables

To use the Polar integration, you need to define the following environment variables to your .env.local as well as your staging and production environments:

POLAR_ACCESS_TOKEN="" # Your Polar access token
POLAR_WEBHOOK_SECRET="" # The secret key of the webhook you created (see above)

Set up products in app

The created products have to be defined in the config/index.ts file:

export const config = {
  payments: {
		plans: {
			free: {
				isFree: true,
			},
			pro: {
				recommended: true,
				prices: [
					{
						type: "recurring",
						productId: process.env.NEXT_PUBLIC_PRODUCT_ID_PRO_MONTHLY as string,
						interval: "month",
						amount: 29,
						currency: "USD",
						seatBased: true,
						trialPeriodDays: 7,
					},
					{
						type: "recurring",
						productId: process.env.NEXT_PUBLIC_PRODUCT_ID_PRO_YEARLY as string,
						interval: "year",
						amount: 290,
						currency: "USD",
						seatBased: true,
						trialPeriodDays: 7,
					},
				],
			},
		},
	},
};

We are using envs for the product ids, so you can define different product ids for each environment, as you probably want to use the test mode for development.

Define the product ids in your .env.local and in the environment variables of your production environment:

NEXT_PUBLIC_PRODUCT_ID_PRO_MONTHLY=""
NEXT_PUBLIC_PRODUCT_ID_PRO_YEARLY=""

Learn more about the payment plans configuration in Manage plans and products documentation.

Set currency for locales in your app

Lastly you need to configure the currency that should be used for each locale in your app.

You can do this by setting the currency property for each locale in the config file.

export const config = {
  i18n: {
    // ...
    locales: {
      en: {
        currency: "USD",
        language: "en",
      },
      de: {
        currency: "EUR",
        language: "de",
      },
    },
  },
  // ...
};