PHPackages mafrasil/cashier-polar - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Payment Processing](/categories/payments) 4. / 5. mafrasil/cashier-polar ActiveLibrary[Payment Processing](/categories/payments) mafrasil/cashier-polar ====================== Laravel Cashier integration for Polar.sh subscription billing services v0.4.5(2mo ago)5175↓62.5%[3 PRs](https://github.com/mafrasil/cashier-polar/pulls)MITPHPPHP ^8.3CI passing Since Dec 21Pushed 1mo ago1 watchersCompare [ Source](https://github.com/mafrasil/cashier-polar)[ Packagist](https://packagist.org/packages/mafrasil/cashier-polar)[ Docs](https://github.com/mafrasil/cashier-polar)[ GitHub Sponsors](https://github.com/mafrasil)[ RSS](/packages/mafrasil-cashier-polar/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (10)Dependencies (11)Versions (25)Used By (0) [![Logo Laravel Cashier](/art/logo.svg)](/art/logo.svg) [![Latest Version on Packagist](https://camo.githubusercontent.com/2c7e85ab57da5eb4d73e578184175da4a4787f822b48aa562607300a6ec00e02/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6d6166726173696c2f636173686965722d706f6c61722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/mafrasil/cashier-polar)[![GitHub Tests Action Status](https://camo.githubusercontent.com/b6f6175ab1faa5839f0f11d513adbc39084cc4fd86fdd4f797cd1b07e25254b2/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6d6166726173696c2f636173686965722d706f6c61722f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/mafrasil/cashier-polar/actions?query=workflow%3Arun-tests+branch%3Amain)[![GitHub Code Style Action Status](https://camo.githubusercontent.com/3eacd499468aec6ec73ed1a938d9fff9641808a0ecbe5e86298c6d55c380567a/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6d6166726173696c2f636173686965722d706f6c61722f6669782d7068702d636f64652d7374796c652d6973737565732e796d6c3f6272616e63683d6d61696e266c6162656c3d636f64652532307374796c65267374796c653d666c61742d737175617265)](https://github.com/mafrasil/cashier-polar/actions?query=workflow%3A%22Fix+PHP+code+style+issues%22+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/0596aeae57811848203f052fb4a5ddea9126928e2116d46a4631368bd3e05f26/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6d6166726173696c2f636173686965722d706f6c61722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/mafrasil/cashier-polar) Disclaimer ---------- [](#disclaimer) > **Note**: This is not an official Laravel package. This is a community-built package following Laravel Cashier principles. Introduction ------------ [](#introduction) Cashier Polar provides an expressive, fluent interface to [Polar's](https://polar.sh) subscription billing services. It handles almost all of the boilerplate subscription billing code you are dreading writing. Table of Contents ----------------- [](#table-of-contents) - [Requirements](#requirements) - [Installation](#installation) - [Configuration](#configuration) - [Basic Usage](#basic-usage) - [Setup Billable Model](#setup-billable-model) - [Create a Checkout Session](#create-a-checkout-session) - [Access Subscriptions](#access-subscriptions) - [Manage Subscriptions](#manage-subscriptions) - [Trials](#trials) - [Products and Pricing](#products-and-pricing) - [Orders and Invoices](#orders-and-invoices) - [Customer Portal](#customer-portal) - [Webhook Events](#webhook-events) - [Listen for Events](#listen-for-events) - [Testing](#testing) - [Credits](#credits) - [License](#license) Requirements ------------ [](#requirements) - PHP 8.3+ - Laravel 10.0+ / 11.0+ - Polar account and API credentials () Installation ------------ [](#installation) ``` composer require mafrasil/cashier-polar php artisan vendor:publish --tag="cashier-polar-migrations" php artisan migrate php artisan vendor:publish --tag="cashier-polar-config" ``` Configuration ------------- [](#configuration) ``` POLAR_API_KEY=your-api-key POLAR_ORGANIZATION_ID=your-organization-id POLAR_WEBHOOK_SECRET=your-webhook-secret POLAR_SANDBOX=true # Set to false for production ``` Generate a webhook secret or grab it from your Polar Webhook settings: ``` php artisan cashier-polar:webhook-secret ``` Basic Usage ----------- [](#basic-usage) ### Setup Billable Model [](#setup-billable-model) ``` use Mafrasil\CashierPolar\Concerns\Billable; class User extends Authenticatable { use Billable; } ``` ### Create a Checkout Session [](#create-a-checkout-session) ``` // Simple checkout with a product ID $checkout = $user->checkout('product_id'); // With options $checkout = $user->checkout('product_id', [ 'success_url' => route('checkout.success'), 'metadata' => [ 'custom_field' => 'value' ] ]); // Redirect to checkout return redirect($checkout['url']); ``` ### Access Subscriptions [](#access-subscriptions) ``` // Get subscription details $subscription = $user->subscription; echo $subscription->name; // Product name (e.g., "Pro") echo $subscription->price; // Formatted price (e.g., "15.00 USD") echo $subscription->interval; // Billing interval (e.g., "month") echo $subscription->description; // Product description echo $subscription->product_id; // Polar product ID // Check subscription status if ($subscription->active()) { // or $user->subscribed() // Subscription is usable if any of: // - Status is active or trialing // - Cancelled but on trial or grace period } // Subscription has been cancelled and on grace period (within billing period) if ($subscription->onGracePeriod()) {} // Subscription has been cancelled and grace period has ended if ($subscription->cancelled()) {} // Subscription has ended if ($subscription->ended()) {} // Period information echo $subscription->currentPeriod(); // "2024-01-01 to 2024-02-01" if ($subscription->withinPeriod()) {} // Check specific product if ($subscription->hasProduct('product_id')) {} // Check specific price plan if ($subscription->hasPlan('price_id')) {} // Payment issues if ($subscription->hasPaymentIssue()) {} ``` ### Manage Subscriptions [](#manage-subscriptions) ``` // Cancel at end of billing period $subscription->cancel(); // Resume a cancelled subscription (before period ends) $subscription->resume(); // Revoke immediately (cancel right now) $subscription->revoke(); // Change to a different product $subscription->change('new_product_id'); // Example usage if ($subscription->onGracePeriod()) { echo "Subscription will cancel on " . $subscription->ends_at->format('Y-m-d'); } elseif ($subscription->cancelled()) { echo "Subscription has been cancelled"; } else { echo "Active " . $subscription->interval . " subscription"; } ``` ### Trials [](#trials) Trials are configured on your products in the Polar dashboard. When a customer subscribes to a product with a trial, the subscription will have `trialing` status. ``` // Check if subscription is on trial if ($subscription->onTrial()) { echo "Trial ends on " . $subscription->trialEndDate(); // "2024-01-15" echo "Days left: " . $subscription->days_until_trial_ends; } // Check if trial has expired if ($subscription->hasExpiredTrial()) {} // End trial early and start paying immediately $subscription->endTrial(); // Cancel during trial (won't convert to paid when trial ends) $subscription->cancel(); // Revoke during trial (ends immediately) $subscription->revoke(); // Trial dates $subscription->trialStart(); // Carbon instance $subscription->trialEnd(); // Carbon instance $subscription->trialEndDate(); // "2024-01-15" ``` The `active()` method returns `true` for trialing subscriptions, so `$user->subscribed()` works seamlessly whether the user is on a trial or a paid plan. ### Products and Pricing [](#products-and-pricing) ``` use Mafrasil\CashierPolar\Facades\CashierPolar; // Get all products $products = CashierPolar::products(); // Get specific product $product = CashierPolar::product('product_id'); // Get products with filters $products = CashierPolar::products([ 'is_archived' => true, // other filters... ]); ``` ### Orders and Invoices [](#orders-and-invoices) In Polar, orders represent payments/invoices. Each time a customer pays (initial purchase, subscription renewal, plan change), an order is created. ``` // Get paid invoices via the customer portal API // Returns only paid orders with rich data: product, subscription, // line items, invoice_number, is_invoice_generated, billing_reason, etc. $invoices = $user->invoices(); // Filter invoices $invoices = $user->invoices([ 'product_id' => 'product_id', 'product_billing_type' => 'recurring', // or 'one_time' 'subscription_id' => 'subscription_id', 'query' => 'Pro Plan', 'page' => 1, 'limit' => 10, 'sorting' => ['-created_at'], ]); // Get all orders via the server-side API (includes all statuses) $orders = $user->orders(); // Generate an invoice PDF for an order (must be called before retrieving) // This triggers Polar to create the invoice PDF — returns 202 (accepted) $user->generateInvoice('order_id'); // Get invoice PDF URL for a specific order // The invoice must be generated first, otherwise this returns null $invoiceUrl = $user->getInvoice('order_id'); // Access local transaction records (stored via webhooks) $transactions = $user->transactions()->get(); // Only completed/paid local transactions $transactions = $user->transactions()->paid()->get(); ``` > **Important**: Polar requires invoices to be generated before they can be retrieved. Call `generateInvoice()` first, wait a few seconds, then call `getInvoice()`. For a reliable approach, listen to the `order.updated` webhook and check the `is_invoice_generated` field before retrieving. ### Customer Portal [](#customer-portal) ``` // Get the Polar customer portal URL for the user $portalUrl = $user->customerPortalUrl(); // With a return URL (shows a back button in the portal) $portalUrl = $user->customerPortalUrl(route('dashboard')); // Redirect to the portal return redirect($portalUrl); ``` ### Webhook Events [](#webhook-events) The package automatically handles these webhook events: - `checkout.created` - `checkout.updated` - `order.created` - `subscription.created` - `subscription.updated` - `subscription.active` - `subscription.revoked` - `subscription.canceled` #### Webhook Configuration [](#webhook-configuration) By default, Cashier Polar listens for webhooks at `/webhooks/polar`. You can customize this path in your `config/cashier-polar.php` configuration file: ``` 'path' => 'custom/webhook/path' ``` Make sure to configure your webhook URL in your Polar dashboard to match your application's webhook endpoint: - URL: `https://your-domain.com/webhooks/polar` (or your custom path) - Secret: Use the value from your `POLAR_WEBHOOK_SECRET` environment variable The package automatically validates webhook signatures to ensure they come from Polar. #### Local Testing with Ngrok [](#local-testing-with-ngrok) For local development, you can use [Ngrok](https://ngrok.com) to create a secure tunnel to your local application: ``` ngrok http 8000 ``` Then use the generated Ngrok URL (e.g., `https://random-string.ngrok.io/webhooks/polar`) as your webhook endpoint in the Polar dashboard. ### Listen for Events [](#listen-for-events) ``` use Mafrasil\CashierPolar\Events\SubscriptionCreated; use Mafrasil\CashierPolar\Events\SubscriptionCanceled; use Mafrasil\CashierPolar\Events\OrderCreated; Event::listen(function (SubscriptionCreated $event) { $subscription = $event->subscription; $user = $subscription->billable; // Handle event }); ``` Testing ------- [](#testing) ``` composer test ``` Credits ------- [](#credits) - [mafrasil](https://github.com/mafrasil) - [All Contributors](../../contributors) License ------- [](#license) The MIT License (MIT). Please see [License File](LICENSE.md) for more information. ### Health Score 46 — FairBetter than 93% of packages Maintenance89 Actively maintained with recent releases Popularity20 Limited adoption so far Community10 Small or concentrated contributor base Maturity53 Maturing project, gaining track record Bus Factor1 Top contributor holds 89.2% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~22 days Recently: every ~0 days Total 21 Last Release 68d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/59563f4ee75edfc67e2071a361b77ecb3d1b58b68c240ce97bbd2ca2ee85f687?d=identicon)[mafrasil](/maintainers/mafrasil) --- Top Contributors [![mafrasil](https://avatars.githubusercontent.com/u/133235707?v=4)](https://github.com/mafrasil "mafrasil (83 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (5 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (5 commits)") --- Tags laravelbillingsubscriptionspolarmafrasilcashier-polar ### Code Quality TestsPest Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/mafrasil-cashier-polar/health.svg) ``` [![Health](https://phpackages.com/badges/mafrasil-cashier-polar/health.svg)](https://phpackages.com/packages/mafrasil-cashier-polar) ``` ### Alternatives [danestves/laravel-polar A package to easily integrate your Laravel application with Polar.sh 7812.3k](/packages/danestves-laravel-polar)[mollie/laravel-cashier-mollie Laravel Cashier provides an expressive, fluent interface to Mollie's subscription billing services. 172155.4k1](/packages/mollie-laravel-cashier-mollie)[musahmusah/laravel-multipayment-gateways A Laravel Package that makes implementation of multiple payment Gateways endpoints and webhooks seamless 852.2k1](/packages/musahmusah-laravel-multipayment-gateways) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)