Create subscriptions with Laravel Polar

Start a subscription checkout, support multiple subscription types per user, and retrieve subscription state with the Billable trait.

Subscriptions are the core of recurring billing in Laravel Polar. The Billable trait gives your model a subscribe() method that redirects a customer to a Polar-hosted checkout. Once payment is complete, the incoming SubscriptionCreated webhook automatically creates and links a Subscription record in your database — no manual wiring needed.

The full flow in one sentence: subscribe() → customer pays on Polar → Polar fires subscription.created webhook → Laravel Polar writes the record → SubscriptionCreated event fires for your listeners.

Starting a subscription

Pass a product ID to subscribe() to begin a checkout session. Laravel Polar attaches the necessary metadata to the checkout automatically so the incoming webhook can associate the subscription with the correct user.

use Illuminate\Http\Request;

Route::get('/subscribe', function (Request $request) {
    return $request->user()->subscribe('product_id_123');
});

The method returns a redirect response to the hosted Polar checkout page.

subscribe() creates a new checkout session on every call. If you call it frequently, cache the returned URL to avoid unnecessary API requests.

Multiple subscription types

A single user can hold more than one active subscription — for example, a “swimming” plan and a “gym” plan at the same time. Pass a subscription type as the second argument to subscribe() to distinguish them:

$checkout = $user->subscribe('product_id_123', 'swimming');

If you omit the type, it defaults to 'default'.

How the webhook connects the subscription

After a successful checkout, Polar sends a subscription.created event to your webhook endpoint. Laravel Polar handles this automatically by dispatching a SubscriptionCreated event and creating a Subscription record in your database, linked to the billable model.

1. Customer completes checkout

   The customer fills in payment details and confirms the subscription on the Polar-hosted checkout page.

2. Polar sends a webhook

   Polar sends a subscription.created payload to your registered webhook URL.

3. Laravel Polar writes the subscription

   The package verifies the signature and creates or updates the subscription record in your database.

4. SubscriptionCreated event is dispatched

   A Danestves\LaravelPolar\Events\SubscriptionCreated event is fired with $event->billable and $event->subscription properties you can listen to.

Make sure your webhook endpoint is reachable and excluded from CSRF protection. See the webhooks guide for setup instructions.

Retrieving a subscription

Once a subscription has been created via the webhook, you can retrieve it from your billable model:

// Retrieve the default subscription
$subscription = $user->subscription();

// Retrieve a named subscription type
$subscription = $user->subscription('swimming');

subscription() returns the first Subscription model matching the given type, or null if none exists. Results are ordered by creation date, most recent first.

Checking subscription status

Use subscribed() to confirm that a user has an active, valid subscription:

if ($user->subscribed()) {
    // The user has a valid default subscription
}

// Check a named subscription type
if ($user->subscribed('swimming')) {
    // The user has a valid swimming subscription
}

subscribed() returns true when the underlying subscription’s valid() check passes, meaning the subscription is active, on trial, past due, or within its grace period after cancellation.

Use subscribed() in middleware or policy checks to gate access to premium features without loading the full subscription model.

Checking subscription to a specific product

To verify that a user is subscribed and that the subscription is currently on a specific product, use subscribedToProduct():

if ($user->subscribedToProduct('product_id_123')) {
    // Valid subscription on this product
}

// Scoped to a named subscription type
if ($user->subscribedToProduct('product_id_123', 'swimming')) {
    // Valid swimming subscription on this product
}

This is useful when you offer multiple products and need to gate features behind a particular plan, not just any subscription.