Plan Items and Add-ons

PlanItem is the structured way to attach priced, quantified add-ons to a plan. Use it whenever a feature has a price, an included quantity, or an overage behaviour — not just a boolean flag.

When to use PlanItem vs features JSON

Use case	Use
Boolean feature flag (`exports: true`)	`Plan.features` JSON column
Simple integer limit (`projects: 10`)	`PlanItem` — migrate from features JSON for entitlement resolution via `included_quantity`
Priced add-on with overage billing	`PlanItem` with `unit_price` and `cap_behavior`
Metered usage charged at period end	`PlanItem` with `pricing_rule = 'metered'`

Booleans stay in features. Anything with a price or quantity goes in PlanItem.

Creating plan items

use Pixelworxio\Subscribd\Models\Plan;
use Pixelworxio\Subscribd\Models\PlanItem;
use Pixelworxio\Subscribd\Enums\CapBehavior;

$pro = Plan::where('key', 'pro')->firstOrFail();

// 3 projects included; $10/mo per additional project; hard cap at 50
PlanItem::create([
    'plan_id'           => $pro->id,
    'key'               => 'projects',
    'name'              => 'Projects',
    'included_quantity' => 3,
    'unit_price'        => 1000,        // $10.00 in minor units (cents)
    'cap_behavior'      => CapBehavior::ChargeUntilCeiling,
    'ceiling'           => 50,
    'sort_order'        => 0,
    'active'            => true,
]);

// 5 team seats included; no overage allowed
PlanItem::create([
    'plan_id'           => $pro->id,
    'key'               => 'team_seats',
    'name'              => 'Team Seats',
    'included_quantity' => 5,
    'unit_price'        => 0,
    'cap_behavior'      => CapBehavior::Block,
    'sort_order'        => 1,
    'active'            => true,
]);

CapBehavior enum

Value	Behaviour
`Block`	Access denied when quantity exceeds `included_quantity`. No billing.
`Charge`	Bill at `unit_price` per unit beyond `included_quantity`, with no ceiling.
`ChargeUntilCeiling`	Bill at `unit_price` per unit up to `ceiling`. Hard block beyond `ceiling`.

SubscriptionItem — per-subscriber state

When a subscriber has a plan with PlanItems, a SubscriptionItem record is created per item at subscription time. SubscriptionItem tracks:

quantity — how many units the subscriber is currently using
price_override / price_override_expires_at — admin-set per-subscriber price
gateway_item_id — the gateway’s item ID for native gateways (Stripe)

// Get a subscriber's current project count
$subscription = $user->subscription();
$item = $subscription->items()->where('key', 'projects')->firstOrFail();
$item->quantity;          // int — current usage
$item->price_override;    // int|null — cents, null if no override

Updating quantities

use Pixelworxio\Subscribd\Actions\UpdateQuantity;

$item = $user->subscription()->items()->where('key', 'projects')->firstOrFail();
app(UpdateQuantity::class)->execute($user->subscription(), quantity: 7, planItemKey: 'projects');

For gateways that manage items natively (Stripe), this also updates the subscription item at the gateway.

Entitlement checks

Entitlements resolves plan items automatically:

use Pixelworxio\Subscribd\Facades\Entitlements;

// How many projects can this user have?
$limit = Entitlements::for($user)->limit('projects');   // int|null (null = unlimited)

// Can they create another project?
$canCreate = $limit === null || ($user->projects()->count() < $limit);

Resolution order:

Check Plan.features[$key] — if a value is set here, use it.
Check PlanItem by key — use included_quantity as the limit.

Price overrides

Apply a per-subscriber price override to any SubscriptionItem:

use Pixelworxio\Subscribd\Actions\SetPriceOverride;
use Carbon\CarbonImmutable;

$item = $user->subscription()->items()->where('key', 'projects')->firstOrFail();

// Permanent override
app(SetPriceOverride::class)->execute(
    subscription: $user->subscription(),
    item: $item,
    price: 500,        // $5.00 per additional project (was $10.00)
    expiresAt: null,
);

// Time-limited override (reverts automatically at renewal)
app(SetPriceOverride::class)->execute(
    subscription: $user->subscription(),
    item: $item,
    price: 0,
    expiresAt: CarbonImmutable::parse('2026-12-31'),
);

When an override’s expires_at passes at renewal, RenewSubscription fires SubscriptionPriceOverrideReverted and reverts to price_snapshot.

Overage billing at renewal

At renewal, RenewSubscription automatically charges overages for items with CapBehavior::Charge or CapBehavior::ChargeUntilCeiling:

overage_units  = max(0, subscription_item.quantity - plan_item.included_quantity)
overage_amount = overage_units × effective_unit_price

effective_unit_price is SubscriptionItem.price_override when active, otherwise PlanItem.unit_price. For gateways with native subscription item support (Stripe), overage is reported via the gateway’s items API and included in the gateway’s renewal invoice. For other gateways, subscribd issues a separate charge() call.

Next steps

Subscriptions — Creating subscriptions with plan items
Entitlements — Checking limits and usage
Multi-Currency — Currency on plan items
Bulk Operations — Bulk price overrides

Getting Started

Billing Scenarios

Subscriptions

Gateways

Entitlements

Invoices & Charges

Coupons

Components

Advanced

Plan Items and Add-ons

Plan Items and Add-ons

When to use PlanItem vs features JSON

Creating plan items

CapBehavior enum

SubscriptionItem — per-subscriber state

Updating quantities

Entitlement checks

Price overrides

Overage billing at renewal

Next steps

​Plan Items and Add-ons

​When to use PlanItem vs features JSON

​Creating plan items

​CapBehavior enum

​SubscriptionItem — per-subscriber state

​Updating quantities

​Entitlement checks

​Price overrides

​Overage billing at renewal

​Next steps

Plan Items and Add-ons

When to use PlanItem vs features JSON

Creating plan items

CapBehavior enum

SubscriptionItem — per-subscriber state

Updating quantities

Entitlement checks

Price overrides

Overage billing at renewal

Next steps