Skip to main content

​
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