Download the PHP package mafrasil/cashier-polar without Composer

Disclaimer

Note: This is not an official Laravel package. This is a community-built package following Laravel Cashier principles.

Introduction

Cashier Polar provides an expressive, fluent interface to Polar's subscription billing services. It handles almost all of the boilerplate subscription billing code you are dreading writing.

Table of Contents

• Requirements
• Installation
• Configuration
• Basic Usage
  • Setup Billable Model
  • Create a Checkout Session
  • Access Subscriptions
  • Manage Subscriptions
  • Trials
  • Products and Pricing
  • Orders and Invoices
  • Customer Portal
  • Webhook Events
  • Listen for Events
• Testing
• Credits
• License

Requirements

• PHP 8.3+
• Laravel 10.0+ / 11.0+
• Polar account and API credentials (https://polar.sh)

Installation

Configuration

Generate a webhook secret or grab it from your Polar Webhook settings:

Basic Usage

Setup Billable Model

Create a Checkout Session

Access Subscriptions

Manage Subscriptions

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.

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

Orders and Invoices

In Polar, orders represent payments/invoices. Each time a customer pays (initial purchase, subscription renewal, plan change), an order is created.

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

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

By default, Cashier Polar listens for webhooks at /webhooks/polar. You can customize this path in your config/cashier-polar.php configuration file:

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

For local development, you can use Ngrok to create a secure tunnel to your local application:

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

Testing

Credits

• mafrasil
• All Contributors

License

The MIT License (MIT). Please see License File for more information.