Polar

Polar supports subscriptions and a hosted customer portal. Use this page if you want Polar with portal access but no invoice previews.

Configuration

<?php

return [
  'bnomei.klub.provider.handler' => \Bnomei\Klub\Provider\PolarProvider::class,
  'bnomei.klub.providers.polar' => [
    'secret' => fn() => env('POLAR_ACCESS_TOKEN'),
    'webhook_secret' => fn() => env('POLAR_WEBHOOK_SECRET'),
    'server' => fn() => env('POLAR_SERVER', 'sandbox'),
    'organization' => fn() => env('POLAR_ORG_SLUG'),
    'field' => 'polar',
  ],
];

Environment variables:

POLAR_ACCESS_TOKEN
POLAR_WEBHOOK_SECRET
POLAR_SERVER (sandbox or production)
POLAR_ORG_SLUG (optional, required for portal links)

Optional provider keys:

org_slug or org (aliases for organization)
webhook_tolerance (seconds, default 300)
checkout for provider-specific checkout payload overrides

Webhooks

Configure webhooks to POST /klub/webhooks/polar.

Polar uses standard webhook headers: webhook-id, webhook-timestamp, and webhook-signature. Klub validates them with POLAR_WEBHOOK_SECRET.

Portal and invoices

Portal: supported when an organization slug is set (organization, org_slug, or org).
Invoice preview: not supported.

Notes

For portal access, set bnomei.klub.providers.polar.organization (or org_slug) to your Polar organization slug.

Plan data (local)

Polar uses local plans (providers.polar.plans or site plans YAML):

id should be the Polar product price ID.
unit_amount and currency are recommended for consistent local catalog output.
type (recurring or one_time) is recommended to help fallback mode detection.
Optional product_id/products can be passed through checkout overrides for advanced cases.

Gotchas

Checkout requires at least one product in the payload. By default Klub uses the selected plan ID.
The “active” subscription filter may exclude trial or cancel-at-period-end states.
Portal URLs require the organization slug and correct server setting.

See Purchases for flow details.

Paypal Stripe