
Polar for Laravel
Seamlessly integrate Polar.sh subscriptions and payments into your Laravel application. This package provides an elegant way to handle subscriptions, manage recurring payments, and interact with Polar’s API. With built-in support for webhooks, subscription management, and a fluent API, you can focus on building your application while we handle the complexities of subscription billing.Installation
Step 1: You can install the package via composer::install
:
Usage
Access Token
Configure your access token. Create a new token in the Polar Dashboard > Settings > Developers and paste it in the.env
file.
- https://sandbox.polar.sh/dashboard/ORG_SLUG/settings (Sandbox)
- https://polar.sh/dashboard/ORG_SLUG/settings (Production)
Webhook Secret
Configure your webhook secret. Create a new webhook in the Polar Dashboard > Settings > Webhooks.- https://sandbox.polar.sh/dashboard/ORG_SLUG/settings/webhooks (Sandbox)
- https://polar.sh/dashboard/ORG_SLUG/settings/webhooks (Production)
order.created
order.updated
subscription.created
subscription.updated
subscription.active
subscription.canceled
subscription.revoked
benefit_grant.created
benefit_grant.updated
benefit_grant.revoked
Billable Trait
Let’s make sure everything’s ready for your customers to checkout smoothly. 🛒 First, we’ll need to set up a model to handle billing—don’t worry, it’s super simple! In most cases, this will be your app’s User model. Just add the Billable trait to your model like this (you’ll import it from the package first, of course):Polar Script
Polar includes a JavaScript script that you can use to initialize the Polar Embedded Checkout. If you going to use this functionality, you can use the@polarEmbedScript
directive to include the script in your views inside the <head>
tag.
Webhooks
This package includes a webhook handler that will handle the webhooks from Polar.Webhooks & CSRF Protection
Incoming webhooks should not be affected by CSRF protection. To prevent this, add your webhook path to the except list of yourApp\Http\Middleware\VerifyCsrfToken
middleware:
polar/*
in your application’s bootstrap/app.php
file:
Commands
This package includes a list of commands that you can use to retrieve information about your Polar account.Command | Description |
---|---|
php artisan polar:products | List all available products with their ids |
Checkouts
Single Payments
To create a checkout to show only a single payment, pass a single items to the array of products when creating the checkout.checkout
method.
[!NOTE]
If you are requesting the checkout a lot of times we recommend you to cache the URL returned by the checkout
method.
Custom Price
You can override the price of a product using thecharge
method.
Embedded Checkout
Instead of redirecting the user you can create the checkout link, pass it to the page and use our blade component:Prefill Customer Information
You can override the user data using the following methods in your models provided by theBillable
trait.
Redirects After Purchase
You can redirect the user to a custom page after the purchase using thewithSuccessUrl
method:
checkout_id={CHECKOUT_ID}
query parameter to the URL to retrieve the checkout session id:
Custom metadata and customer metadata
You can add custom metadata to the checkout session using thewithMetadata
method:
withCustomerMetadata
method:
Reserved Keywords
When working with custom data, this library has a few reserved terms.billable_id
billable_type
subscription_type
Customers
Customer Portal
Customers can update their personal information (e.g., name, email address) by accessing their self-service customer portal. To redirect customers to this portal, call theredirectToCustomerPortal()
method on your billable model (e.g., the User model).
Orders
Retrieving Orders
You can retrieve orders by using theorders
relationship on the billable model:
Check order status
You can check the status of an order by using thestatus
attribute:
Order
model:
Subscriptions
Creating Subscriptions
Starting a subscription is simple. For this, we require our product’s variant id. Copy the product id and start a new subscription checkout using your billable model:SubscriptionCreated
event webhook connects it to your billable model in the database. You may then get the subscription from your billable model:
Checking Subscription Status
Once a consumer has subscribed to your services, you can use a variety of methods to check on the status of their subscription. The most basic example is to check if a customer has a valid subscription.valid
method:
Cancelled Status
To see if a user has cancelled their subscription, you can use the cancelled method:onGracePeriod
check.
Past Due Status
If a recurring payment fails, the subscription will become past due. This indicates that the subscription is still valid, but your customer’s payments will be retried in two weeks.Subscription Scopes
There are several subscription scopes available for querying subscriptions in specific states:Changing Plans
When a consumer is on a monthly plan, they may desire to upgrade to a better plan, alter their payments to an annual plan, or drop to a lower-cost plan. In these cases, you can allow them to swap plans by giving a different product id to theswap
method:
swapAndInvoice
method instead.
Multiple Subscriptions
In certain situations, you may wish to allow your consumer to subscribe to numerous subscription kinds. For example, a gym may provide a swimming and weight lifting subscription. You can let your customers subscribe to one or both. To handle the various subscriptions, you can offer a type of subscription as the second argument when creating a new one:Cancelling Subscriptions
To cancel a subscription, call thecancel
method.
onGracePeriod
method:
Subscription Trials
[!NOTE] Coming soon.
Handling Webhooks
Polar can send webhooks to your app, allowing you to react. By default, this package handles the majority of the work for you. If you have properly configured webhooks, it will listen for incoming events and update your database accordingly. We recommend activating all event kinds so you may easily upgrade in the future.Webhook Events
Danestves\LaravelPolar\Events\BenefitGrantCreated
Danestves\LaravelPolar\Events\BenefitGrantUpdated
Danestves\LaravelPolar\Events\BenefitGrantRevoked
Danestves\LaravelPolar\Events\OrderCreated
Danestves\LaravelPolar\Events\OrderRefunded
Danestves\LaravelPolar\Events\SubscriptionActive
Danestves\LaravelPolar\Events\SubscriptionCanceled
Danestves\LaravelPolar\Events\SubscriptionCreated
Danestves\LaravelPolar\Events\SubscriptionRevoked
Danestves\LaravelPolar\Events\SubscriptionUpdated
$model
object and an event $payload
. The subscription events also include the $subscription
object. These can be accessed via the public properties.
If you wish to respond to these events, you must establish listeners for them. For example, you may wish to react when a subscription is updated.
EventServiceProvider
:
Roadmap
- Add support for trials Polar itself doesn’t support trials, but we can manage them by ourselves.