Billable Models

A billable is any Eloquent model that can hold subscriptions. Typically this is your User model, but it can be any model — a Team, Organisation, or Project works equally well.

Setting up a billable model

Implement the Billable contract and add the ManagesBilling trait:

<?php

namespace App\Models;

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;
}

That’s it. The trait wires up all relationships and helper methods automatically.

Register the billable type

Add your billable class to config/subscribd.php under the billables key:

'billables' => [
    'user' => \App\Models\User::class,
],

The key (user) is used internally when storing polymorphic relationships and in the Filament admin panel’s transfer action dropdown.

Multiple billable types

You can register as many billable types as your application needs:

'billables' => [
    'user' => \App\Models\User::class,
    'team' => \App\Models\Team::class,
],

Each model implements Billable and uses ManagesBilling independently.

Relationships

The ManagesBilling trait provides the following Eloquent relationships:

$user->subscriptions();     // MorphMany — all subscriptions
$user->invoices();          // MorphMany — all invoices
$user->paymentMethods();    // MorphMany — stored payment methods
$user->featureUsage();      // MorphMany — usage records
$user->apiTokens();         // MorphMany — REST API tokens

Subscription helpers

// Retrieve a named subscription (default name is 'default')
$subscription = $user->subscription();
$subscription = $user->subscription('team_plan');

// Check subscription state
$user->subscribed();                    // has an active or trialing subscription
$user->subscribed('team_plan');         // named subscription
$user->onTrial();                       // currently in a trial period
$user->onGracePeriod();                 // canceled but within the grace period

Invoice helpers

$user->latestInvoice();     // most recent Invoice model
$user->paidInvoices();      // MorphMany scoped to status=paid, newest first
$user->openInvoices();      // MorphMany scoped to status=open, newest first
$user->totalPaid();         // integer sum of all paid invoices in minor units

Payment method helpers

$user->defaultPaymentMethod();  // the PaymentMethod marked as default, or null

Billing identity

Subscribd reads these methods when communicating with gateways. Override them if your model uses different column names:

$user->billingEmail();      // falls back to $this->email
$user->billingName();       // falls back to $this->name
$user->billingCurrency();   // currency of the active subscription, or config default

To use a different column or a computed value, override the method on your model:

public function billingEmail(): string
{
    return $this->contact_email ?? $this->email;
}

Gateway customer IDs

Subscribd stores gateway customer IDs in a JSON column on your billable table. Run the migration published by vendor:publish --tag=subscribd-migrations to add this column, or add it manually:

$table->json('subscribd_gateway_customer_ids')->nullable();

To read or write a customer ID:

$user->gatewayCustomerId('stripe');                    // read
$user->setGatewayCustomerId('stripe', 'cus_abc123');   // write

If you’re migrating from a setup that stored IDs in per-gateway columns (subscribd_stripe_id, etc.), the getter falls back to those columns automatically. Run php artisan subscribd:migrate-customer-ids to backfill the JSON column.

Next steps

Plans — Define your pricing tiers
Creating Subscriptions — Subscribe a billable to a plan
Checking Features — Gate application features by plan

Getting Started

Billing Scenarios

Subscriptions

Gateways

Entitlements

Invoices & Charges

Coupons

Components

Advanced

Billable Models

Billable Models

Setting up a billable model

Register the billable type

Multiple billable types

Relationships

Subscription helpers

Invoice helpers

Payment method helpers

Billing identity

Gateway customer IDs

Next steps

​Billable Models

​Setting up a billable model

​Register the billable type

​Multiple billable types

​Relationships

​Subscription helpers

​Invoice helpers

​Payment method helpers

​Billing identity

​Gateway customer IDs

​Next steps

Billable Models

Setting up a billable model

Register the billable type

Multiple billable types

Relationships

Subscription helpers

Invoice helpers

Payment method helpers

Billing identity

Gateway customer IDs

Next steps