README

Filament v5 admin panel plugin for managing vouchers powered by the aiarmada/vouchers package.

Features

• Complete Voucher Management – create, edit, view, and delete vouchers with a rich Filament UI
• Usage Tracking – monitor redemptions, discounts applied, and user activity
• Wallet System – allow users to save vouchers for later use
• Dashboard Widgets – stats overview, redemption trends, and usage timelines
• Cart Integration – seamless voucher application when aiarmada/filament-cart is installed
• Multi-Tenant Support – owner-scoped resources for marketplace scenarios
• Targeting Configuration – define preset targeting rules for vouchers
• Stacking Rules – configure how vouchers combine with each other

Installation

composer require aiarmada/filament-vouchers

Register the plugin in your panel provider:

use AIArmada\FilamentVouchers\FilamentVouchersPlugin;

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

Publish the configuration:

php artisan vendor:publish --tag=filament-vouchers-config

Configuration

// config/filament-vouchers.php
return [
    // Navigation group for resources
    'navigation_group' => 'E-commerce',

    // Default currency for monetary displays
    'default_currency' => 'MYR',

    // Table polling interval (seconds or null to disable)
    'polling_interval' => 60,

    // Resource navigation ordering
    'resources' => [
        'navigation_sort' => [
            'vouchers' => 40,
            'voucher_usage' => 41,
        ],
    ],

    // Order resource for linking (set class-string or null)
    'order_resource' => null,

    // Owner types for multi-tenant voucher assignment
    'owners' => [],
];

Resources

Voucher Resource

Manage vouchers with full CRUD operations:

• Code & Name – unique voucher identifier and display name
• Type – percentage, fixed amount, or free shipping
• Value – discount amount with currency support
• Usage Limits – global and per-user redemption limits
• Scheduling – start and expiry dates
• Conditions – target rules via DSL presets
• Owner Assignment – multi-tenant voucher ownership

Voucher Usage Resource

Track all voucher redemptions:

• User/redeemer information
• Discount amounts applied
• Redemption channel (automatic, manual, API)
• Order linking when configured

Widgets

The plugin provides these dashboard widgets:

Cart Integration

When aiarmada/filament-cart is installed, the plugin automatically enables:

• Deep linking from usage records to cart views
• Voucher application actions on cart pages
• Applied voucher widgets on cart detail pages

Using Cart Actions

Add voucher actions to your cart resource pages:

use AIArmada\FilamentVouchers\Extensions\CartVoucherActions;

protected function getHeaderActions(): array
{
    return [
        CartVoucherActions::applyVoucher(),
        CartVoucherActions::showAppliedVouchers(),
    ];
}

Available actions:

• applyVoucher() – modal form to enter and apply a voucher code
• showAppliedVouchers() – modal displaying currently applied vouchers
• removeVoucher($code) – remove a specific voucher from cart

Multi-Tenant Ownership

Configure owner types to enable voucher assignment to specific entities:

// config/filament-vouchers.php
'owners' => [
    [
        'label' => 'Store',
        'model' => App\Models\Store::class,
        'title_attribute' => 'name',
        'subtitle_attribute' => 'email',      // Optional
        'search_attributes' => ['name', 'code'],
    ],
    [
        'label' => 'Vendor',
        'model' => App\Models\Vendor::class,
        'title_attribute' => 'company_name',
        'search_attributes' => ['company_name', 'email'],
    ],
],

When configured, a searchable owner selector appears in the voucher form.

Global vouchers keep both owner_type and owner_id set to null; empty strings are not used as sentinels.

Documentation

• Overview – Package introduction and quick start
• Installation – Installation guide
• Configuration – All configuration options
• Usage – Resources, pages, and actions
• Widgets – Available widgets and customization
• Cart Integration – Voucher-cart integration guide
• Troubleshooting – Common issues and solutions

License

MIT License. See LICENSE for details.