Skip to main content
This guide walks you through the complete path from a fresh installation to a working subscription. By the end you will have a billable User model, a plan defined in config, that plan synced to your database, and a live subscription created through the Subscribd facade.
1

Install the package

If you have not installed Subscribd yet, follow the installation guide first. The short version:
composer require pixelworxio/subscribd
php artisan subscribd:install
php artisan migrate
2

Make your User model billable

Open app/Models/User.php and implement the Billable contract, use the ManagesBilling trait, and add the two billing methods that Subscribd uses to generate invoices and create gateway customers.
app/Models/User.php
use Illuminate\Foundation\Auth\User as Authenticatable;
use Pixelworxio\Subscribd\Concerns\ManagesBilling;
use Pixelworxio\Subscribd\Contracts\Billable;

class User extends Authenticatable implements Billable
{
    use ManagesBilling;

    // Subscribd reads this to generate invoices and create gateway customers.
    public function billingEmail(): string
    {
        return $this->email;
    }

    public function billingName(): string
    {
        return $this->name;
    }
}
Any Eloquent model — Team, Organization, or otherwise — can be made billable the same way. The Billable contract is not limited to User.
3

Register billable types in config

Open config/subscribd.php and add your billable models under the billables key. The array key becomes the type identifier Subscribd uses internally.
config/subscribd.php
'billables' => [
    'user' => \App\Models\User::class,
    'team' => \App\Models\Team::class,
],
4

Define a plan

Add a plan to the plans array in config/subscribd.php. All prices are in minor currency units — 1900 means $19.00 for USD. The features array drives entitlement checks later.
config/subscribd.php
'plans' => [
    'starter' => [
        'name'           => 'Starter',
        'description'    => 'Full product access for individuals.',
        'rule'           => 'flat',
        'price'          => 1900,       // $19.00/month
        'currency'       => 'USD',
        'interval'       => 'month',
        'interval_count' => 1,
        'trial_days'     => 14,
        'features'       => [
            'projects'   => 5,
            'api_access' => true,
            'support'    => 'email',
        ],
    ],
],
Subscribd supports four pricing rules: flat, per_unit, tiered, and metered. See the Pricing Models section for a full breakdown of each.
5

Sync plans to the database

Run the plan sync command to insert or update the subscribd_plans table from your config. Re-run this command any time you add or modify a plan.
php artisan subscribd:plan sync
You can verify the result with:
php artisan subscribd:plan list
6

Subscribe a user

Use the Subscribd facade to create a subscription. Pass the plan key you defined in config.
use Pixelworxio\Subscribd\Facades\Subscribd;

Subscribd::for($user)->subscribe('starter');
If you need more control, you can also resolve the plan from the database and use the CreateSubscription action directly:
use Pixelworxio\Subscribd\Actions\CreateSubscription;
use Pixelworxio\Subscribd\Models\Plan;

$plan = Plan::query()->where('key', 'starter')->firstOrFail();
app(CreateSubscription::class)->execute($user, $plan);
7

Check subscription status

Once the subscription is created, you can check its status anywhere in your application using the helper methods added by the ManagesBilling trait.
$user->subscribed();               // true if the user has any active or trialing subscription
$user->subscribed('default');      // true if the named subscription is active or trialing
$user->onTrial('default');         // true if the subscription is in a trial period
$user->onGracePeriod('default');   // true if canceled but the period has not yet ended
You can also gate features against the plan’s entitlements:
$ent = Subscribd::entitlements()->for($user);

$ent->allows('api_access');          // bool
$ent->limitOf('projects');           // int|null (null means unlimited)
$ent->allows('support', 'email');    // value comparison
To protect a controller action:
abort_unless(Subscribd::entitlements()->for($user)->allows('api_access'), 403);

​
What’s next

Pricing models

Explore per-seat, tiered, and metered pricing in addition to the flat-rate plan you just created.

Gateway configuration

Set your .env credentials for Stripe, PayPal, or Braintree and point your webhook endpoint.

Entitlements

Gate features and enforce plan limits across your entire application.

UI components

Add a plan picker, checkout form, and invoice history to your app with a single Blade tag.