README

A unified product catalog for SaaS billing in Laravel. Define catalog items with recurring or metered pricing, manage their lifecycle from draft to published, and expose an optional API — all without coupling to any specific billing provider.

Key Concepts

• Catalog Items — billable products with a type (Recurring or Metered), a unique SKU, and a managed lifecycle (Draft → Published → Disabled)
• Recurring Prices — fixed-amount price points billed at configurable intervals (daily, weekly, monthly, quarterly, semi-annual, annual)
• Metered Prices — tiered pricing based on consumption using Volume or Graduated strategies
• Polymorphic Registration — attach catalog items to any Eloquent model (servers, plans, features, etc.)
• Price History — prices are never deleted; syncing disables old prices and creates new ones, preserving a full audit trail

Installation

composer require settleup/catalog

Publish and run the migrations:

php artisan vendor:publish --tag="catalog-migrations"
php artisan migrate

Optionally publish the config:

php artisan vendor:publish --tag="catalog-config"

Usage

Creating Catalog Items

use SettleUp\Catalog\Actions\CreateCatalogItem;
use SettleUp\Catalog\DataTransferObjects\CatalogItemData;
use SettleUp\Catalog\Enums\CatalogItemType;

$item = CreateCatalogItem::make()->handle(
    new CatalogItemData(
        type: CatalogItemType::Recurring,
        name: 'Pro Plan',
        sku: 'pro-plan',
        description: 'Access to all pro features',
    )
);

Managing the Item Lifecycle

Items follow a strict lifecycle: Draft → Published → Disabled. A published item can be disabled and re-enabled, but can never return to draft.

use SettleUp\Catalog\Actions\PublishCatalogItem;
use SettleUp\Catalog\Actions\DisableCatalogItem;
use SettleUp\Catalog\Actions\EnableCatalogItem;

// Publish a draft item
PublishCatalogItem::make()->handle($item);

// Disable it (removes from active catalog)
DisableCatalogItem::make()->handle($item);

// Re-enable it
EnableCatalogItem::make()->handle($item);

Setting Recurring Prices

use SettleUp\Catalog\Actions\SyncRecurringPrices;
use SettleUp\Catalog\DataTransferObjects\RecurringPriceData;
use SettleUp\Catalog\Enums\RecurringInterval;

SyncRecurringPrices::make()->handle($item, [
    new RecurringPriceData(amount: 1999, interval: RecurringInterval::Monthly),
    new RecurringPriceData(amount: 19999, interval: RecurringInterval::Annual),
]);

Setting Metered Prices

use SettleUp\Catalog\Actions\SyncMeteredPrices;
use SettleUp\Catalog\DataTransferObjects\MeteredPriceData;
use SettleUp\Catalog\Enums\PricingStrategy;

SyncMeteredPrices::make()->handle($item, [
    new MeteredPriceData(
        pricingStrategy: PricingStrategy::Graduated,
        minUnits: 0,
        maxUnits: 100,
        pricePerUnit: 10,
        flatFee: 500,
    ),
    new MeteredPriceData(
        pricingStrategy: PricingStrategy::Graduated,
        minUnits: 101,
        maxUnits: null, // unlimited
        pricePerUnit: 5,
    ),
]);

All monetary amounts are stored as integers in cents.

Attaching to Eloquent Models

Use the HasCatalogItems concern to associate catalog items with any model:

use SettleUp\Catalog\Concerns\HasCatalogItems;
use SettleUp\Catalog\Enums\CatalogItemType;

class Server extends Model
{
    use HasCatalogItems;
}

$server->registerCatalogItem(CatalogItemType::Metered, [
    'name' => 'Bandwidth',
    'sku' => 'server-bandwidth',
]);

Registering API Routes

The package provides an optional REST API. Register the routes inside your own route group to control middleware, prefixing, and authentication:

use SettleUp\Catalog\Facades\Catalog;

Route::prefix('api')
    ->middleware(['auth:sanctum'])
    ->group(function () {
        Catalog::routes()->register();
    });

You can limit which routes are registered:

// Only register specific routes
Catalog::routes()->only(['index', 'show', 'store'])->register();

// Register all except certain routes
Catalog::routes()->except(['enable', 'disable'])->register();

Available API Endpoints

Permissions

Every API endpoint is gated by a configurable permission. Set a permission to null to skip authorization for that action:

// config/catalog.php
return [
    'permissions' => [
        'catalog-items' => [
            'index'   => 'catalog:view',
            'store'   => 'catalog:create',
            'show'    => 'catalog:view',
            'update'  => 'catalog:update',
            'publish' => 'catalog:publish',
            'enable'  => 'catalog:update',
            'disable' => 'catalog:update',
        ],
        'recurring-prices' => [
            'index' => 'catalog:view',
            'sync'  => 'catalog:update',
        ],
        'metered-prices' => [
            'index' => 'catalog:view',
            'sync'  => 'catalog:update',
        ],
    ],
];

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Andrew Leach
• All Contributors

License

The MIT License (MIT). Please see License File for more information.