Configure Laravel Polar: tokens, webhooks, and more

Configure your Polar access token, organization ID, server environment, webhook secret, route path, redirect URL, and currency locale.

After installation, open config/polar.php to review every option. All secrets are read from environment variables — add them to your .env file and never commit them to version control. The sections below explain each setting, where to find the required values in the Polar dashboard, and what the defaults mean.

Quick start: The minimum you need to get going is POLAR_ACCESS_TOKEN and POLAR_WEBHOOK_SECRET. Everything else has a sensible default.

Access token

POLAR_ACCESS_TOKEN="your_access_token"

// config/polar.php
'access_token' => env('POLAR_ACCESS_TOKEN'),

The access token authenticates all API requests the package makes on behalf of your organisation. Create one in the Polar dashboard under Settings → Developers:

• Sandbox: https://sandbox.polar.sh/dashboard/<org_slug>/settings
• Production: https://polar.sh/dashboard/<org_slug>/settings

Keep your access token out of source control. Store it in .env and make sure .env is listed in .gitignore.

Organization ID (optional)

POLAR_ORGANIZATION_ID="your_organization_id"

'organization_id' => env('POLAR_ORGANIZATION_ID'),

Most API calls derive the organisation from your access token automatically. However, the public-facing license key methods — validateLicenseKey, activateLicenseKey, and deactivateLicenseKey — require an explicit organisation ID. Setting it here once means you never have to pass it on every call. If you leave it unset you must pass the organizationId argument explicitly every time you call those methods.

Server environment

POLAR_SERVER="sandbox"

'server' => env('POLAR_SERVER', 'sandbox'),

Value	Base URL	Use for
sandbox (default)	https://sandbox-api.polar.sh	Local development, CI, staging
production	https://api.polar.sh	Live customers

The default is sandbox — you can test checkouts, subscriptions, and webhooks with no risk to real customer data. Remember to switch to production before going live.

Use a separate Polar organisation (or the same org’s sandbox mode) during development. That way test orders and subscriptions never pollute your production data.

Webhook secret

POLAR_WEBHOOK_SECRET="your_webhook_secret"

'webhook_secret' => env('POLAR_WEBHOOK_SECRET'),

The package verifies every incoming request using the webhook secret, so only genuine Polar payloads are processed. Create a webhook in the Polar dashboard under Settings → Webhooks:

• Sandbox: https://sandbox.polar.sh/dashboard/<org_slug>/settings/webhooks
• Production: https://polar.sh/dashboard/<org_slug>/settings/webhooks

Set the webhook URL to https://yourdomain.com/polar/webhook (replace polar if you have customised POLAR_PATH).

Supported events

Subscribe your webhook to all of the following event types so the package can react to every billing lifecycle change. If an event type is missing, the corresponding Laravel event won’t be dispatched and your database may fall out of sync.

Category	Events
Order	order.created, order.updated
Subscription	subscription.created, subscription.updated, subscription.active, subscription.canceled, subscription.revoked
Benefit grant	benefit_grant.created, benefit_grant.updated, benefit_grant.revoked
Checkout	checkout.created, checkout.updated, checkout.expired
Customer	customer.created, customer.updated, customer.deleted, customer.state_changed
Product	product.created, product.updated
Benefit	benefit.created, benefit.updated

The Polar documentation recommends using a single webhook endpoint per environment. One endpoint, one secret — no need to manage multiple configurations.

Route path

POLAR_PATH="polar"

'path' => env('POLAR_PATH', 'polar'),

This is the URI prefix for all routes the package registers. The default polar produces:

• POST /polar/webhook — webhook endpoint
• GET /polar/... — any other package routes

Change this if polar conflicts with an existing route in your application. Remember to update the webhook URL in the Polar dashboard to match.

Default redirect URL

'redirect_url' => null,

When a customer completes a Polar checkout they are redirected back to your application. Set a default URL here and the package will use it for every checkout session unless you override it with ->withSuccessUrl(...) at call time.

// config/polar.php
'redirect_url' => env('POLAR_REDIRECT_URL', '/dashboard'),

Currency locale

POLAR_CURRENCY_LOCALE="en"

'currency_locale' => env('POLAR_CURRENCY_LOCALE', 'en'),

Controls how monetary amounts are formatted when displayed to users (e.g. in order summaries or invoices). Examples:

Locale	Format
en (default)	$1,234.56
de	1.234,56 $
fr	1 234,56 €

Any valid ICU locale string is accepted.

Non-English locales require the PHP intl extension. Run php -m | grep intl to confirm it is enabled on your server.

Full example .env

POLAR_ACCESS_TOKEN="polar_pat_xxxxxxxxxxxxxxxxxxxx"
POLAR_ORGANIZATION_ID="org_xxxxxxxxxxxxxxxxxxxx"
POLAR_SERVER="production"
POLAR_WEBHOOK_SECRET="whsec_xxxxxxxxxxxxxxxxxxxx"
POLAR_PATH="polar"
POLAR_CURRENCY_LOCALE="en"

Next steps

Billable trait

Add billing capabilities to your Eloquent models.

Webhooks

Learn how to listen for and handle Polar webhook events in your application.