DOCSEARCHbyAlgolia
Submit Docs

Laravel Cashier Stripe

repository·16.x·Indexed 25 days ago

https://github.com/laravel/cashier-stripe

An expressive, fluent interface for managing Stripe subscription billing services in Laravel. It automates boilerplate subscription logic and supports features such as basic subscription management, coupons, swapping plans, quantity updates, cancellation grace periods, metered billing, and invoice PDF generation. Includes tools for handling SCA/3DS incomplete payments, webhook configuration, and testing with Stripe test cards and tokens.

Tokens
17.1K
Snippets
32
Records
125
Agent score
81%

What's inside laravel-cashier-stripe

  1. Introduction to Laravel Cashier Stripe

    16.x

    Laravel Cashier provides an expressive, fluent interface for managing Stripe subscription billing services. It automates boilerplate subscription logic and supports advanced billing features such as:

    • Basic subscription management
    • Coupons
    • Swapping subscriptions
    • Subscription 'quantities'
    • Cancellation grace periods
    • Generating invoice PDFs

  2. Handle Non-Stripe Customers in Cashier 11.x

    16.x

    In Cashier 11.x, methods that previously threw an InvalidStripeCustomer exception when a user was not yet a Stripe customer now return empty/null values instead:

    • invoices(): Returns an empty collection.
    • paymentMethods(): Returns an empty collection.
    • upcomingInvoice(): Returns null.

  3. Handle Proration Changes in Cashier 12.x

    16.x

    Cashier 12.x updates proration features to use Stripe's proration_behavior options.

    Key changes:

    • The xAndInvoice method will now always generate a new invoice in a single request using the always_invoice option, rather than requiring a separate HTTP request.
    • The $prorate property has been renamed to $prorationBehavior.
    • The setProrate method has been renamed to setProrationBehavior.

  5. Understand Cashier's auto-registered webhook routes

    16.x

    Cashier automatically registers two routes using the prefix defined in config('cashier.path') (defaults to stripe).

    • POST /{cashier.path}/webhook (named cashier.webhook): Receives incoming Stripe webhook events.
    • GET /{cashier.path}/payment/{id} (named cashier.payment): Used for handling payment flows.

    If you change the CASHIER_PATH environment variable to billing, the routes will become /billing/webhook and /billing/payment/{id}.

  6. Handle cascading invoice exceptions in 14.x

    16.x

    In Cashier 14, Stripe exceptions during invoicing methods (invoice, invoiceFor, invoicePrice) are no longer caught internally and returned as false. Instead, these exceptions will bubble up to your application. You must implement error handling for these exceptions in your code.

    Note: CardException instances are still caught internally to trigger IncompletePayment exceptions.

  7. Configure Stripe API Version for Cashier 11.x

    16.x
    Cashier 11.x uses Stripe API version 2020-03-02. It is recommended to update your Stripe Dashboard settings to match this version after deploying the upgrade. If you use the Stripe SDK directly, ensure you test your integration thoroughly.

  8. Migrate to Payment Methods API

    16.x

    Cashier 10.0 has migrated from the Sources and Tokens API to the recommended Stripe Payment Methods API.

    Transitioning from Sources/Tokens

    While the Payment Methods API is backwards compatible, you should update your integration as soon as possible. If a user does not have a Laravel\/Cashier\/PaymentMethod attached, defaultPaymentMethod() may return an instance of Stripe\Card or Stripe\BankAccount instead. You should handle this to migrate them to the new API:

    use Stripe\Card as StripeCard;
use Stripe\BankAccount as StripeBankAccount;

$defaultPaymentMethod = $user->defaultPaymentMethod();

if ($defaultPaymentMethod instanceof StripeCard ||
    $defaultPaymentMethod instanceof StripeBankAccount) {
    // Gather payment method and store it using new payment method APIs...
}

    Single Charges

    The charge method no longer accepts a token. It now requires a payment method identifier as the second parameter:

    $user->charge(1000, $paymentMethod);

  9. Handle card failures during plan swaps in version 9.3+

    16.x

    In version 9.3, when a user attempts to swap subscription plans and the payment fails, Cashier allows the plan swap to proceed in Stripe to prevent your application and Stripe from becoming out of sync. The payment failure is handled by Stripe's retry logic.

    To ensure your application correctly reflects the subscription status (e.g., marking it as canceled if all retries fail), you must configure Cashier to handle Stripe webhooks. Refer to the official documentation for setting up Stripe webhooks with Cashier.

  10. Use checkout redirects instead of the Checkout Button in 14.x

    16.x

    The built-in checkout button has been removed in Cashier 14. You should now handle the checkout redirect from a controller:

    use Illuminate\Http\Request;
 
Route::get('/product-checkout', function (Request $request) {
    return $request->user()->checkout('price_tshirt');
});
    use Illuminate
	
Route::get('/product-checkout', function (Request $request) {
    return $request->user()->checkout('price_tshirt');
});

  11. Configure payment methods for Checkout in 14.x

    16.x

    In Cashier 14, users manage payment methods via the Stripe Dashboard by default. To restore the previous behavior where Cashier sets cards as the default payment method, explicitly pass payment_method_types in the options array:

    $request->user()->checkout('price_tshirt', [
    'payment_method_types' => ['card'],
]);

  12. Update database schema for Cashier 16.0

    16.x

    To support usage-based billing tracking (specifically the new meter_id and meter_event_name fields), you must publish and run the Cashier migrations.

    php artisan vendor:publish --tag="cashier-migrations"

php artisan migrate