> ## Documentation Index
> Fetch the complete documentation index at: https://docs.subscribd.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Billable Models

> Mark any Eloquent model as billable and access its subscriptions, invoices, and payment methods

# 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 theme={null}
<?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:

```php theme={null}
'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:

```php theme={null}
'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:

```php theme={null}
$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

```php theme={null}
// 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

```php theme={null}
$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

```php theme={null}
$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:

```php theme={null}
$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:

```php theme={null}
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:

```php theme={null}
$table->json('subscribd_gateway_customer_ids')->nullable();
```

To read or write a customer ID:

```php theme={null}
$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](/getting-started/plans)** — Define your pricing tiers
* **[Creating Subscriptions](/subscriptions/creating)** — Subscribe a billable to a plan
* **[Checking Features](/entitlements/checking-features)** — Gate application features by plan