Connect Polar so your customers can pay for listing packages. This page walks you through every field, the webhook, and product mapping, step by step.

Polar is a Merchant of Record Merchant of Record With Polar, Polar is the legal seller of your subscriptions. That means Polar handles sales tax and VAT for you, worldwide. Access to a customer’s listing package is webhook-gated: the plugin grants and revokes access based on the signed webhook messages Polar sends. If the webhook is not set up correctly, customers may pay but not get access. Take your time on the webhook step below.

What you will need

  • A Polar account and organization.
  • A Polar organization access token.
  • A few minutes to register a webhook endpoint and copy a signing secret.

Important: pick one environment and stick to it Polar has a Sandbox environment for testing and a Production environment for real sales. Your Environment setting, your access token, your webhook secret, and your product IDs must all belong to the same environment. Mixing a sandbox token with production product IDs (or the reverse) will not work.

Step 1: Choose Polar in the Settings tab

  1. In your WordPress admin, open the plugin’s Settings tab.
  2. Using the provider logo toggle, choose Polar as your active provider.
  3. The Polar fields appear. We fill them in over the next steps.

The Polar settings fields

  1. Environment – A dropdown with two choices: Sandbox (the default) and Production. Sandbox is for testing and talks to the host sandbox-api.polar.sh. Production is for real, live sales and talks to api.polar.sh. Choose Sandbox while you test, then switch to Production when you are ready to take real money.
  2. Access token – A password field. This is a Polar organization access token that lets the plugin create checkout sessions, read subscriptions, and create customer sessions. One token belongs to one environment, so a sandbox token only works in Sandbox and a production token only works in Production.
  3. Webhook secret – The signing secret for your Polar webhook endpoint. The plugin uses it to confirm that incoming webhook messages really came from Polar. You get this value in Step 3 below.
Polar Settings in Listeo Subscriptions

Step 2: Create a Polar access token

  1. Log in to your Polar dashboard. If you are testing, use the Sandbox dashboard so your token matches your Environment setting.
  2. Open your organization settings and find the access tokens page
  3. Create a new organization access token. Make sure it can create checkout sessions, read subscriptions, and create customer sessions.
  4. Copy the token.
  5. Back in the plugin Settings tab, paste it into the Access token field.

Enable also “allow multiple subscriptions” option

Tip Copy the token the moment Polar shows it. Like most secrets, it is usually only shown once. If you lose it, just create a new one.

Step 3: Register the webhook in Polar

This is the most important step. The webhook is how Polar tells the plugin when someone subscribes, cancels, or fails a payment, which is what grants and revokes access.

The endpoint URL

In Polar, go to Settings > Webhooks and add a new endpoint. Use this URL, replacing YOUR-SITE.com with your own site address:

https://YOUR-SITE.com/wp-json/listeo-recurring-packages/v1/polar/webhook

Warning: use the “Raw” webhook format When Polar asks for the payload format, choose Raw, not the default. The plugin verifies Polar webhooks using the Standard Webhooks signature scheme, and that only works with the Raw format. If you leave the default format, signature verification will fail and access will not be granted.

Subscribe to these events

Turn on each of these events for the endpoint:

  • checkout.updated
  • checkout.expired
  • subscription.created
  • subscription.updated
  • subscription.active
  • subscription.past_due
  • subscription.uncanceled
  • subscription.canceled
  • subscription.revoked

Copy the signing secret

  1. After creating the endpoint, Polar shows a webhook signing secret. It may start with whsec_.
  2. Copy it.
  3. Back in the plugin Settings tab, paste it into the Webhook secret field (polar_webhook_secret).
  4. Save your settings.

Important: keep your server clock accurate Webhook signatures are time-checked, with a 5 minute tolerance. If your server’s clock is wrong by more than a few minutes, valid webhooks will be rejected and access will not update. If you run into trouble, ask your host to confirm the server time is correct.

Step 4: Create your product and map it to a package

Polar does not let the plugin create products for you. You create the product in Polar, then paste its ID into the plugin for each listing package.

  1. In your Polar dashboard, create the product (with the recurring price) you want to sell.
  2. Open the product and copy its product ID. In Polar this is a UUID, a long id that looks like 12345678-90ab-....
  3. In the plugin, go to the Products tab.
  4. For the package you want to sell, paste the ID into Sandbox Polar product ID or Production Polar product ID, depending on which environment you are using.
  5. Save.

Add products ID to plugin settings

Note Checkout is hosted by Polar at buy.polar.sh. When a customer buys a package, the plugin sends them to a secure Polar-hosted checkout page, so you never handle card details yourself.

Match the environment Paste your sandbox product UUID into the Sandbox field and your production product UUID into the Production field. The product IDs must match the same environment as your Environment setting, access token, and webhook secret.

For full details on the Products tab and how packages map to products, see Products & packages.

Customers can manage their own subscription

Good news: Polar has a customer billing portal. That means your customers get a working Manage button where they can update their payment method and cancel on their own, without contacting you.

Tip Test the whole flow in Sandbox first: subscribe with a test card, confirm the package access is granted, then cancel from the Manage button and confirm access is revoked. When everything works, switch your Environment to Production and re-enter your production access token, webhook secret, and product IDs.