Laravel Cashier (Paddle)
- Introduction
- Upgrading Cashier
- Installation
- Configuration
- Core Concepts
- Prices
- Customers
- Subscriptions
- Subscription Trials
- Handling Paddle Webhooks
- Single Charges
- Receipts
- Handling Failed Payments
- Testing
Introduction
At this time, Cashier Paddle only supports Paddle Classic, which is not available to new Paddle customers unless you contact Paddle support.
Laravel Cashier Paddle provides an expressive, fluent interface to Paddle's subscription billing services. It handles almost all of the boilerplate subscription billing code you are dreading. In addition to basic subscription management, Cashier can handle: coupons, swapping subscription, subscription "quantities", cancellation grace periods, and more.
While working with Cashier we recommend you also review Paddle's user guides and API documentation.
Upgrading Cashier
When upgrading to a new version of Cashier, it's important that you carefully review the upgrade guide.
Installation
First, install the Cashier package for Paddle using the Composer package manager:
To ensure Cashier properly handles all Paddle events, remember to set up Cashier's webhook handling.
Paddle Sandbox
During local and staging development, you should register a Paddle Sandbox account. This account will give you a sandboxed environment to test and develop your applications without making actual payments. You may use Paddle's test card numbers to simulate various payment scenarios.
When using the Paddle Sandbox environment, you should set the PADDLE_SANDBOX environment variable to true within your application's .env file:
After you have finished developing your application you may apply for a Paddle vendor account. Before your application is placed into production, Paddle will need to approve your application's domain.
Database Migrations
The Cashier service provider registers its own database migration directory, so remember to migrate your database after installing the package. The Cashier migrations will create a new customers table. In addition, a new subscriptions table will be created to store all of your customer's subscriptions. Finally, a new receipts table will be created to store all of your application's receipt information:
If you need to overwrite the migrations that are included with Cashier, you can publish them using the vendor:publish Artisan command:
If you would like to prevent Cashier's migrations from running entirely, you may use the ignoreMigrations provided by Cashier. Typically, this method should be called in the register method of your AppServiceProvider:
Configuration
Billable Model
Before using Cashier, you must add the Billable trait to your user model definition. This trait provides various methods to allow you to perform common billing tasks, such as creating subscriptions, applying coupons and updating payment method information:
If you have billable entities that are not users, you may also add the trait to those classes:
API Keys
Next, you should configure your Paddle keys in your application's .env file. You can retrieve your Paddle API keys from the Paddle control panel:
The PADDLE_SANDBOX environment variable should be set to true when you are using Paddle's Sandbox environment. The PADDLE_SANDBOX variable should be set to false if you are deploying your application to production and are using Paddle's live vendor environment.
Paddle JS
Paddle relies on its own JavaScript library to initiate the Paddle checkout widget. You can load the JavaScript library by placing the @paddleJS Blade directive right before your application layout's closing </head> tag:
Currency Configuration
The default Cashier currency is United States Dollars (USD). You can change the default currency by defining a CASHIER_CURRENCY environment variable within your application's .env file:
In addition to configuring Cashier's currency, you may also specify a locale to be used when formatting money values for display on invoices. Internally, Cashier utilizes PHP's NumberFormatter class to set the currency locale:
In order to use locales other than en, ensure the ext-intl PHP extension is installed and configured on your server.
Overriding Default Models
You are free to extend the models used internally by Cashier by defining your own model and extending the corresponding Cashier model:
After defining your model, you may instruct Cashier to use your custom model via the Laravel\Paddle\Cashier class. Typically, you should inform Cashier about your custom models in the boot method of your application's App\Providers\AppServiceProvider class:
Core Concepts
Pay Links
Paddle lacks an extensive CRUD API to perform subscription state changes. Therefore, most interactions with Paddle are done through its checkout widget. Before we can display the checkout widget, we must generate a "pay link" using Cashier. A "pay link" will inform the checkout widget of the billing operation we wish to perform:
Cashier includes a paddle-button Blade component. We may pass the pay link URL to this component as a "prop". When this button is clicked, Paddle's checkout widget will be displayed:
By default, this will display a button with the standard Paddle styling. You can remove all Paddle styling by adding the data-theme="none" attribute to the component:
The Paddle checkout widget is asynchronous. Once the user creates or updates a subscription within the widget, Paddle will send your application webhooks so that you may properly update the subscription state in our own database. Therefore, it's important that you properly set up webhooks to accommodate for state changes from Paddle.
For more information on pay links, you may review the Paddle API documentation on pay link generation.
After a subscription state change, the delay for receiving the corresponding webhook is typically minimal but you should account for this in your application by considering that your user's subscription might not be immediately available after completing the checkout.
Manually Rendering Pay Links
You may also manually render a pay link without using Laravel's built-in Blade components. To get started, generate the pay link URL as demonstrated in previous examples:
Next, simply attach the pay link URL to an a element in your HTML:
Payments Requiring Additional Confirmation
Sometimes additional verification is required in order to confirm and process a payment. When this happens, Paddle will present a payment confirmation screen. Payment confirmation screens presented by Paddle or Cashier may be tailored to a specific bank or card issuer's payment flow and can include additional card confirmation, a temporary small charge, separate device authentication, or other forms of verification.
Inline Checkout
If you don't want to make use of Paddle's "overlay" style checkout widget, Paddle also provides the option to display the widget inline. While this approach does not allow you to adjust any of the checkout's HTML fields, it allows you to embed the widget within your application.
To make it easy for you to get started with inline checkout, Cashier includes a paddle-checkout Blade component. To get started, you should generate a pay link and pass the pay link to the component's override attribute:
To adjust the height of the inline checkout component, you may pass the height attribute to the Blade component:
Inline Checkout Without Pay Links
Alternatively, you may customize the widget with custom options instead of using a pay link:
Please consult Paddle's guide on Inline Checkout as well as their parameter reference for further details on the inline checkout's available options.
If you would like to also use the passthrough option when specifying custom options, you should provide a key / value array as its value. Cashier will automatically handle converting the array to a JSON string. In addition, the customer_id passthrough option is reserved for internal Cashier usage.
Manually Rendering An Inline Checkout
You may also manually render an inline checkout without using Laravel's built-in Blade components. To get started, generate the pay link URL as demonstrated in previous examples.
Next, you may use Paddle.js to initialize the checkout. To keep this example simple, we will demonstrate this using Alpine.js; however, you are free to translate this example to your own frontend stack:
User Identification
In contrast to Stripe, Paddle users are unique across all of Paddle, not unique per Paddle account. Because of this, Paddle's API's do not currently provide a method to update a user's details such as their email address. When generating pay links, Paddle identifies users using the customer_email parameter. When creating a subscription, Paddle will try to match the user provided email to an existing Paddle user.
In light of this behavior, there are some important things to keep in mind when using Cashier and Paddle. First, you should be aware that even though subscriptions in Cashier are tied to the same application user, they could be tied to different users within Paddle's internal systems. Secondly, each subscription has its own connected payment method information and could also have different email addresses within Paddle's internal systems (depending on which email was assigned to the user when the subscription was created).
Therefore, when displaying subscriptions you should always inform the user which email address or payment method information is connected to the subscription on a per-subscription basis. Retrieving this information can be done with the following methods provided by the Laravel\Paddle\Subscription model:
There is currently no way to modify a user's email address through the Paddle API. When a user wants to update their email address within Paddle, the only way for them to do so is to contact Paddle customer support. When communicating with Paddle, they need to provide the paddleEmail value of the subscription to assist Paddle in updating the correct user.
Prices
Paddle allows you to customize prices per currency, essentially allowing you to configure different prices for different countries. Cashier Paddle allows you to retrieve all of the prices for a given product using the productPrices method. This method accepts the product IDs of the products you wish to retrieve prices for:
The currency will be determined based on the IP address of the request; however, you may optionally provide a specific country to retrieve prices for:
After retrieving the prices you may display them however you wish:
You may also display the net price (excludes tax) and display the tax amount separately:
If you retrieved prices for subscription plans you can display their initial and recurring price separately:
For more information, check Paddle's API documentation on prices.
Customers
If a user is already a customer and you would like to display the prices that apply to that customer, you may do so by retrieving the prices directly from the customer instance:
Internally, Cashier will use the user's paddleCountry method to retrieve the prices in their currency. So, for example, a user living in the United States will see prices in USD while a user in Belgium will see prices in EUR. If no matching currency can be found the default currency of the product will be used. You can customize all prices of a product or subscription plan in the Paddle control panel.
Coupons
You may also choose to display prices after a coupon reduction. When calling the productPrices method, coupons may be passed as a comma delimited string:
Then, display the calculated prices using the price method:
You may display the original listed prices (without coupon discounts) using the listPrice method:
When using the prices API, Paddle only allows applying coupons to one-time purchase products and not to subscription plans.
Customers
Customer Defaults
Cashier allows you to define some useful defaults for your customers when creating pay links. Setting these defaults allow you to pre-fill a customer's email address, country, and postal code so that they can immediately move on to the payment portion of the checkout widget. You can set these defaults by overriding the following methods on your billable model:
These defaults will be used for every action in Cashier that generates a pay link.
Subscriptions
Creating Subscriptions
To create a subscription, first retrieve an instance of your billable model from your database, which typically will be an instance of App\Models\User. Once you have retrieved the model instance, you may use the newSubscription method to create the model's subscription pay link:
The first argument passed to the newSubscription method should be the internal name of the subscription. If your application only offers a single subscription, you might call this default or primary. This subscription name is only for internal application usage and is not meant to be shown to users. In addition, it should not contain spaces and it should never be changed after creating the subscription. The second argument given to the newSubscription method is the specific plan the user is subscribing to. This value should correspond to the plan's identifier in Paddle. The returnTo method accepts a URL that your user will be redirected to after they successfully complete the checkout.
The create method will create a pay link which you can use to generate a payment button. The payment button can be generated using the paddle-button Blade component that is included with Cashier Paddle:
After the user has finished their checkout, a subscription_created webhook will be dispatched from Paddle. Cashier will receive this webhook and setup the subscription for your customer. In order to make sure all webhooks are properly received and handled by your application, ensure you have properly setup webhook handling.
Additional Details
If you would like to specify additional customer or subscription details, you may do so by passing them as an array of key / value pairs to the create method. To learn more about the additional fields supported by Paddle, check out Paddle's documentation on generating pay links:
Coupons
If you would like to apply a coupon when creating the subscription, you may use the withCoupon method:
Metadata
You can also pass an array of metadata using the withMetadata method:
When providing metadata, please avoid using subscription_name as a metadata key. This key is reserved for internal use by Cashier.
Checking Subscription Status
Once a user is subscribed to your application, you may check their subscription status using a variety of convenient methods. First, the subscribed method returns true if the user has an active subscription, even if the subscription is currently within its trial period:
The subscribed method also makes a great candidate for a route middleware, allowing you to filter access to routes and controllers based on the user's subscription status:
If you would like to determine if a user is still within their trial period, you may use the onTrial method. This method can be useful for determining if you should display a warning to the user that they are still on their trial period:
The subscribedToPlan method may be used to determine if the user is subscribed to a given plan based on a given Paddle plan ID. In this example, we will determine if the user's default subscription is actively subscribed to the monthly plan:
The recurring method may be used to determine if the user is currently subscribed and is no longer within their trial period:
Cancelled Subscription Status
To determine if the user was once an active subscriber but has cancelled their subscription, you may use the cancelled method:
You may also determine if a user has cancelled their subscription, but are still on their "grace period" until the subscription fully expires. For example, if a user cancels a subscription on March 5th that was originally scheduled to expire on March 10th, the user is on their "grace period" until March 10th. Note that the subscribed method still returns true during this time:
To determine if the user has cancelled their subscription and is no longer within their "grace period", you may use the ended method:
Past Due Status
If a payment fails for a subscription, it will be marked as past_due. When your subscription is in this state it will not be active until the customer has updated their payment information. You may determine if a subscription is past due using the pastDue method on the subscription instance:
When a subscription is past due, you should instruct the user to update their payment information. You may configure how past due subscriptions are handled in your Paddle subscription settings.
If you would like subscriptions to still be considered active when they are past_due, you may use the keepPastDueSubscriptionsActive method provided by Cashier. Typically, this method should be called in the register method of your AppServiceProvider:
When a subscription is in a past_due state it cannot be changed until payment information has been updated. Therefore, the swap and updateQuantity methods will throw an exception when the subscription is in a past_due state.
Subscription Scopes
Most subscription states are also available as query scopes so that you may easily query your database for subscriptions that are in a given state:
A complete list of available scopes is available below:
Subscription Single Charges
Subscription single charges allow you to charge subscribers with a one-time charge on top of their subscriptions:
In contrast to single charges, this method will immediately charge the customer's stored payment method for the subscription. The charge amount should always be defined in the currency of the subscription.
Updating Payment Information
Paddle always saves a payment method per subscription. If you want to update the default payment method for a subscription, you should first generate a subscription "update URL" using the updateUrl method on the subscription model:
Then, you may use the generated URL in combination with Cashier's provided paddle-button Blade component to allow the user to initiate the Paddle widget and update their payment information:
When a user has finished updating their information, a subscription_updated webhook will be dispatched by Paddle and the subscription details will be updated in your application's database.
Changing Plans
After a user has subscribed to your application, they may occasionally want to change to a new subscription plan. To update the subscription plan for a user, you should pass the Paddle plan's identifier to the subscription's swap method:
If you would like to swap plans and immediately invoice the user instead of waiting for their next billing cycle, you may use the swapAndInvoice method:
Plans may not be swapped when a trial is active. For additional information regarding this limitation, please see the Paddle documentation.
Prorations
By default, Paddle prorates charges when swapping between plans. The noProrate method may be used to update the subscriptions without prorating the charges:
Subscription Quantity
Sometimes subscriptions are affected by "quantity". For example, a project management application might charge $10 per month per project. To easily increment or decrement your subscription's quantity, use the incrementQuantity and decrementQuantity methods:
Alternatively, you may set a specific quantity using the updateQuantity method:
The noProrate method may be used to update the subscription's quantity without prorating the charges:
Subscription Modifiers
Subscription modifiers allow you to implement metered billing or extend subscriptions with add-ons.
For example, you might want to offer a "Premium Support" add-on with your standard subscription. You can create this modifier like so:
The example above will add a $12.99 add-on to the subscription. By default, this charge will recur on every interval you have configured for the subscription. If you would like, you can add a readable description to the modifier using the modifier's description method:
To illustrate how to implement metered billing using modifiers, imagine your application charges per SMS message sent by the user. First, you should create a $0 plan in your Paddle dashboard. Once the user has been subscribed to this plan, you can add modifiers representing each individual charge to the subscription:
As you can see, we invoked the oneTime method when creating this modifier. This method will ensure the modifier is only charged once and does not recur every billing interval.
Retrieving Modifiers
You may retrieve a list of all modifiers for a subscription via the modifiers method:
Deleting Modifiers
Modifiers may be deleted by invoking the delete method on a Laravel\Paddle\Modifier instance:
Multiple Subscriptions
Paddle allows your customers to have multiple subscriptions simultaneously. For example, you may run a gym that offers a swimming subscription and a weight-lifting subscription, and each subscription may have different pricing. Of course, customers should be able to subscribe to either or both plans.
When your application creates subscriptions, you may provide the name of the subscription to the newSubscription method. The name may be any string that represents the type of subscription the user is initiating:
In this example, we initiated a monthly swimming subscription for the customer. However, they may want to swap to a yearly subscription at a later time. When adjusting the customer's subscription, we can simply swap the price on the swimming subscription:
Of course, you may also cancel the subscription entirely:
Pausing Subscriptions
To pause a subscription, call the pause method on the user's subscription:
When a subscription is paused, Cashier will automatically set the paused_from column in your database. This column is used to know when the paused method should begin returning true. For example, if a customer pauses a subscription on March 1st, but the subscription was not scheduled to recur until March 5th, the paused method will continue to return false until March 5th. This is done because a user is typically allowed to continue using an application until the end of their billing cycle.
You may determine if a user has paused their subscription but are still on their "grace period" using the onPausedGracePeriod method:
To resume a paused a subscription, you may call the unpause method on the user's subscription:
A subscription cannot be modified while it is paused. If you want to swap to a different plan or update quantities you must resume the subscription first.
Cancelling Subscriptions
To cancel a subscription, call the cancel method on the user's subscription:
When a subscription is cancelled, Cashier will automatically set the ends_at column in your database. This column is used to know when the subscribed method should begin returning false. For example, if a customer cancels a subscription on March 1st, but the subscription was not scheduled to end until March 5th, the subscribed method will continue to return true until March 5th. This is done because a user is typically allowed to continue using an application until the end of their billing cycle.
You may determine if a user has cancelled their subscription but are still on their "grace period" using the onGracePeriod method:
If you wish to cancel a subscription immediately, you may call the cancelNow method on the user's subscription:
Paddle's subscriptions cannot be resumed after cancellation. If your customer wishes to resume their subscription, they will have to subscribe to a new subscription.
Subscription Trials
With Payment Method Up Front
While trialing and collecting payment method details up front, Paddle prevents any subscription changes such as swapping plans or updating quantities. If you want to allow a customer to swap plans during a trial the subscription must be cancelled and recreated.
If you would like to offer trial periods to your customers while still collecting payment method information up front, you should use the trialDays method when creating your subscription pay links:
This method will set the trial period ending date on the subscription record within your application's database, as well as instruct Paddle to not begin billing the customer until after this date.
If the customer's subscription is not cancelled before the trial ending date they will be charged as soon as the trial expires, so you should be sure to notify your users of their trial ending date.
You may determine if the user is within their trial period using either the onTrial method of the user instance or the onTrial method of the subscription instance. The two examples below are equivalent:
To determine if an existing trial has expired, you may use the hasExpiredTrial methods:
Defining Trial Days In Paddle / Cashier
You may choose to define how many trial days your plan's receive in the Paddle dashboard or always pass them explicitly using Cashier. If you choose to define your plan's trial days in Paddle you should be aware that new subscriptions, including new subscriptions for a customer that had a subscription in the past, will always receive a trial period unless you explicitly call the trialDays(0) method.
Without Payment Method Up Front
If you would like to offer trial periods without collecting the user's payment method information up front, you may set the trial_ends_at column on the customer record attached to your user to your desired trial ending date. This is typically done during user registration:
Cashier refers to this type of trial as a "generic trial", since it is not attached to any existing subscription. The onTrial method on the User instance will return true if the current date is not past the value of trial_ends_at:
Once you are ready to create an actual subscription for the user, you may use the newSubscription method as usual:
To retrieve the user's trial ending date, you may use the trialEndsAt method. This method will return a Carbon date instance if a user is on a trial or null if they aren't. You may also pass an optional subscription name parameter if you would like to get the trial ending date for a specific subscription other than the default one:
You may use the onGenericTrial method if you wish to know specifically that the user is within their "generic" trial period and has not created an actual subscription yet:
There is no way to extend or modify a trial period on a Paddle subscription after it has been created.
Handling Paddle Webhooks
Paddle can notify your application of a variety of events via webhooks. By default, a route that points to Cashier's webhook controller is registered by the Cashier service provider. This controller will handle all incoming webhook requests.
By default, this controller will automatically handle cancelling subscriptions that have too many failed charges (as defined by your Paddle dunning settings), subscription updates, and payment method changes; however, as we'll soon discover, you can extend this controller to handle any Paddle webhook event you like.
To ensure your application can handle Paddle webhooks, be sure to configure the webhook URL in the Paddle control panel. By default, Cashier's webhook controller responds to the /paddle/webhook URL path. The full list of all webhooks you should enable in the Paddle control panel are:
- Subscription Created
- Subscription Updated
- Subscription Cancelled
- Payment Succeeded
- Subscription Payment Succeeded
Make sure you protect incoming requests with Cashier's included webhook signature verification middleware.
Webhooks & CSRF Protection
Since Paddle webhooks need to bypass Laravel's CSRF protection, be sure to list the URI as an exception in your App\Http\Middleware\VerifyCsrfToken middleware or list the route outside of the web middleware group:
Webhooks & Local Development
For Paddle to be able to send your application webhooks during local development, you will need to expose your application via a site sharing service such as Ngrok or Expose. If you are developing your application locally using Laravel Sail, you may use Sail's site sharing command.
Defining Webhook Event Handlers
Cashier automatically handles subscription cancellation on failed charges and other common Paddle webhooks. However, if you have additional webhook events you would like to handle, you may do so by listening to the following events that are dispatched by Cashier:
-
Laravel\Paddle\Events\WebhookReceived -
Laravel\Paddle\Events\WebhookHandled
Both events contain the full payload of the Paddle webhook. For example, if you wish to handle the invoice.payment_succeeded webhook, you may register a listener that will handle the event:
Once your listener has been defined, you may register it within your application's EventServiceProvider:
Cashier also emit events dedicated to the type of the received webhook. In addition to the full payload from Paddle, they also contain the relevant models that were used to process the webhook such as the billable model, the subscription, or the receipt:
-
Laravel\Paddle\Events\PaymentSucceeded -
Laravel\Paddle\Events\SubscriptionPaymentSucceeded -
Laravel\Paddle\Events\SubscriptionCreated -
Laravel\Paddle\Events\SubscriptionUpdated -
Laravel\Paddle\Events\SubscriptionCancelled
You can also override the default, built-in webhook route by defining the CASHIER_WEBHOOK environment variable in your application's .env file. This value should be the full URL to your webhook route and needs to match the URL set in your Paddle control panel:
Verifying Webhook Signatures
To secure your webhooks, you may use Paddle's webhook signatures. For convenience, Cashier automatically includes a middleware which validates that the incoming Paddle webhook request is valid.
To enable webhook verification, ensure that the PADDLE_PUBLIC_KEY environment variable is defined in your application's .env file. The public key may be retrieved from your Paddle account dashboard.
Single Charges
Simple Charge
If you would like to make a one-time charge against a customer, you may use the charge method on a billable model instance to generate a pay link for the charge. The charge method accepts the charge amount (float) as its first argument and a charge description as its second argument:
After generating the pay link, you may use Cashier's provided paddle-button Blade component to allow the user to initiate the Paddle widget and complete the charge:
The charge method accepts an array as its third argument, allowing you to pass any options you wish to the underlying Paddle pay link creation. Please consult the Paddle documentation to learn more about the options available to you when creating charges:
Charges happen in the currency specified in the cashier.currency configuration option. By default, this is set to USD. You may override the default currency by defining the CASHIER_CURRENCY environment variable in your application's .env file:
You can also override prices per currency using Paddle's dynamic pricing matching system. To do so, pass an array of prices instead of a fixed amount:
Charging Products
If you would like to make a one-time charge against a specific product configured within Paddle, you may use the chargeProduct method on a billable model instance to generate a pay link:
Then, you may provide the pay link to the paddle-button component to allow the user to initialize the Paddle widget:
The chargeProduct method accepts an array as its second argument, allowing you to pass any options you wish to the underlying Paddle pay link creation. Please consult the Paddle documentation regarding the options that are available to you when creating charges:
Refunding Orders
If you need to refund a Paddle order, you may use the refund method. This method accepts the Paddle order ID as its first argument. You may retrieve the receipts for a given billable model using the receipts method:
You may optionally specify a specific amount to refund as well as a reason for the refund:
You can use the $refundRequestId as a reference for the refund when contacting Paddle support.
Receipts
You may easily retrieve an array of a billable model's receipts via the receipts property:
When listing the receipts for the customer, you may use the receipt instance's methods to display the relevant receipt information. For example, you may wish to list every receipt in a table, allowing the user to easily download any of the receipts:
Past & Upcoming Payments
You may use the lastPayment and nextPayment methods to retrieve and display a customer's past or upcoming payments for recurring subscriptions:
Both of these methods will return an instance of Laravel\Paddle\Payment; however, nextPayment will return null when the billing cycle has ended (such as when a subscription has been cancelled):
Handling Failed Payments
Subscription payments fail for various reasons, such as expired cards or a card having insufficient funds. When this happens, we recommend that you let Paddle handle payment failures for you. Specifically, you may setup Paddle's automatic billing emails in your Paddle dashboard.
Alternatively, you can perform more precise customization by listening for the subscription_payment_failed Paddle event via the WebhookReceived event dispatched by Cashier. You should also ensure the "Subscription Payment Failed" option is enabled in the Webhook settings of your Paddle dashboard:
Once your listener has been defined, you should register it within your application's EventServiceProvider:
Testing
While testing, you should manually test your billing flow to make sure your integration works as expected.
For automated tests, including those executed within a CI environment, you may use Laravel's HTTP Client to fake HTTP calls made to Paddle. Although this does not test the actual responses from Paddle, it does provide a way to test your application without actually calling Paddle's API.