> ## 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.

# Filament Integration

> Install the Subscribd Filament plugin and manage billing from your admin panel

# Filament Integration

Subscribd ships a first-party Filament plugin — `pixelworxio/subscribd-filament` — that adds a complete billing admin panel to your Filament application. It includes resources, relation managers, dashboard widgets, and bulk operations out of the box.

## Installation

### 1. Install the plugin package

```bash theme={null}
composer require pixelworxio/subscribd-filament
```

### 2. Register the plugin with your Filament panel

```php theme={null}
use Pixelworxio\Subscribd\Filament\SubscribdFilamentPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            SubscribdFilamentPlugin::make(),
        ]);
}
```

That's it. The plugin auto-registers all resources, widgets, and relation managers.

## Resources

The plugin registers four resources:

| Resource               | Model          | Pages              |
| ---------------------- | -------------- | ------------------ |
| `PlanResource`         | `Plan`         | List, Create, Edit |
| `SubscriptionResource` | `Subscription` | List, View         |
| `InvoiceResource`      | `Invoice`      | List, View         |
| `CouponResource`       | `Coupon`       | List, Create, Edit |

### PlanResource

Manage plans and their PlanItems from a single resource:

* **Plan table** — key (copyable), name, rule, amount, interval, active status, subscription count
* **Plan form** — all plan fields plus a live `PlanItemsRelationManager` for managing composable add-ons
* **PlanItemsRelationManager** — inline CRUD for PlanItems with cap behaviour, ceiling, included quantity, overage price, and sort order

### SubscriptionResource

The subscription list provides search, status filter, plan filter, and gateway filter. The view page shows all subscription fields and exposes the following header actions:

| Action                  | Visible when                         |
| ----------------------- | ------------------------------------ |
| Swap plan               | Active, Trialing, Past Due, or Grace |
| Cancel subscription     | Active, Trialing, Past Due, or Grace |
| Resume subscription     | Grace status                         |
| Extend trial            | Trialing                             |
| Convert trial to active | Trialing                             |
| Cancel trial            | Trialing                             |
| Transfer subscription   | Active, Trialing, Past Due, or Grace |

The view page also includes a `SubscriptionItemsRelationManager` showing per-item quantities, cap behaviour badges, effective prices, and a quantity-update action with cap enforcement.

### InvoiceResource

Read-only invoice view with all invoice fields and an `InvoiceLinesRelationManager` showing line items. Header action to issue a refund when the invoice is paid.

### CouponResource

Full CRUD for coupons with a **Deactivate** table action that sets `expires_at = now()` on any valid coupon.

## Dashboard widgets

The plugin registers the following `StatsOverviewWidget` classes:

| Widget                      | Shows                                                                           |
| --------------------------- | ------------------------------------------------------------------------------- |
| `ActiveSubscriptionsWidget` | Active count, Trialing count, Past Due count                                    |
| `MrrWidget`                 | Monthly Recurring Revenue normalised across billing intervals; multi-currency   |
| `ArrWidget`                 | Annual Recurring Revenue from the latest `ArrSnapshot`; "as of" date            |
| `FailedPaymentsWidget`      | Failed payment count and recent failed payment list; configurable lookback days |
| `TrialWidget`               | Active trial count, average days remaining, 30-day conversion rate              |
| `TrialConversionWidget`     | Conversion rate over a configurable window (monthly/quarterly/annual)           |
| `SeatsWidget`               | Seats in use, at-capacity items, items with overages                            |

Add individual widgets to your dashboard by registering them explicitly, or let the plugin register all of them automatically via `SubscribdFilamentPlugin::make()`.

## Bulk operations

The `BulkOperationsWidget` provides a three-stage confirmation UI for batch operations across subscriptions:

* Cancel subscriptions in bulk
* Resume subscriptions in bulk
* Extend trials in bulk
* Apply coupons in bulk
* Transfer subscriptions in bulk
* Retry failed payments in bulk

The widget uses an Alpine confirmation gate before executing destructive operations and shows a per-subscription success/failure breakdown in the results stage.

## Subscription price overrides

The `SubscriptionPriceOverride` Livewire component is composed into the Subscription view page. It lists all `SubscriptionItems` with their current effective prices and override status, and provides a form to:

* Set a permanent per-item price override
* Set a time-limited override with an expiry date
* Clear an existing override

## Admin panel access

The built-in admin panel (without Filament) is available at `subscribd/admin` and is gated by the `can:manage-billing` policy. If you prefer to use the Filament plugin as your admin interface, disable the built-in panel:

```php theme={null}
// config/subscribd.php
'admin' => [
    'enabled' => false,
],
```

## Authorization

Protect Filament resources with standard Filament authorization. Register a policy for any Subscribd model:

```php theme={null}
// AppServiceProvider::boot()
Gate::policy(\Pixelworxio\Subscribd\Models\Invoice::class, InvoicePolicy::class);
```

Subscribd does not ship policies — this is intentional, as billing access rules vary significantly between applications.

## Next steps

* **[Testing](/advanced/testing)** — Test billing flows with the FakeGateway
* **[Webhooks](/advanced/webhooks)** — Handle gateway events
* **[Hooks and Events](/advanced/hooks-and-events)** — React to billing milestones