README

Cashier provides subscription billing for Laravel applications. It handles the recurring billing flow and now uses a product-based catalog (plans, add-ons, and other billable items) attached to each subscription.

Table of Contents

• Cashier
  • Table of Contents
  • Installation
  • Publishing Config and Migrations
  • Products
  • Subscribable Model
  • Subscriptions
  • Billing
  • Upgrade Notes (Plan to Product)
  • Contributing
  • License

Installation

Install via Composer:

composer require jeanfprado/cashier

The package supports auto-discovery. If auto-discovery is disabled, register the service provider manually:

Jeanfprado\Cashier\CashierServiceProvider::class,

Optional facade alias:

'Cashier' => Jeanfprado\Cashier\Support\Facade\Cashier::class,

Publishing Config and Migrations

Publish only the config:

php artisan vendor:publish --tag=cashier-config

Publish only the migrations:

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

Then run migrations:

php artisan migrate

Products

Define your products in config/cashier.php under cashier.products.

Each product supports:

• name
• description (optional)
• type (Plan, Add-on, Other)
• amount (decimal)
• value (metric value, optional business meaning)
• operation (increment or decrement)
• settings (optional JSON)
• options (optional JSON)

Seed products from config:

php artisan cashier:seed-products

Subscribable Model

Set the subscribable model in config/cashier.php:

'model' => App\Models\User::class,

Your model must implement the contract and use the trait:

<?php

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Jeanfprado\Cashier\Subscribable;
use Jeanfprado\Cashier\Contracts\Subscribable as SubscribableContract;

class User extends Authenticatable implements SubscribableContract
{
    use Subscribable;
}

Subscriptions

Create a subscription by passing one or more Product models:

use Jeanfprado\Cashier\Models\Product;
use Jeanfprado\Cashier\Models\Subscription;

$products = Product::whereIn('slug_name', ['extra-storage', 'additional-seats'])->get();

$subscription = $user->subscribe(
    $products,
    Subscription::TYPE_MONTHLY, // monthly, triennial, semestrial, yearly
    7 // optional trial days; falls back to config('cashier.trial_days')
);

Add or remove products on an existing subscription:

$subscription->addProduct($product, 2);   // attach or increment quantity
$subscription->removeProduct($product);   // detach

Cancel the current subscription:

$user->cancelSubscription();

Billing

Generate due billings for all subscriptions:

php artisan cashier:subscription-check

Or generate from code for a single subscription:

if ($subscription->canGenerateBilling() && ! $subscription->hasBillingPending()) {
    $billing = $subscription->generateBilling();
}

Mark a billing as paid:

$billing->markToPaid();

Upgrade Notes (Plan to Product)

Recent migrations replaced the old plans relation with a product catalog + pivot (subscription_products).

• Existing plan records are migrated into products.
• Existing subscriptions are linked to migrated products.
• subscriptions.plan_id is replaced by subscriptions.type.
• The legacy plans table is removed.

If you are upgrading an existing installation, publish/update migrations and run:

php artisan migrate

After migrating, review config/cashier.php and run cashier:seed-products to add any new catalog items.

Contributing

Thank you for considering contributing to Cashier.

License

Cashier is open-sourced software licensed under the MIT license.