Skip to main content
Entitlements translate the features map on a plan into runtime checks your application can use to gate access, enforce limits, and surface usage data to users. Rather than writing raw queries against subscription or plan records, you call the entitlement API with a feature key and let Subscribd resolve the correct value for the billable’s current plan.

​
Basic access checks

Get an entitlement checker for a billable with Subscribd::entitlements()->for($billable), then call the method that matches what you need: 
$ent = Subscribd::entitlements()->for($user);

$ent->allows('api_access');          // bool — true if feature is truthy
$ent->limitOf('projects');           // int|null — null means unlimited
$ent->value('support');              // mixed — the raw feature value
$ent->allows('support', 'priority'); // value comparison — true if value equals 'priority'

​
Gating controller actions

The most common usage pattern is to abort with a 403 if a feature is not allowed: 
abort_unless(Subscribd::entitlements()->for($user)->allows('api_access'), 403);
For limit enforcement, check the remaining quota before creating a new resource: 
$remaining = Subscribd::entitlements()->for($user)->remaining('projects', $user);

abort_unless($remaining === null || $remaining > 0, 403);
remaining() returns null when the plan has unlimited access, and an integer otherwise. A null result means there is no cap, so the action should always be allowed.

​
Checking limits and remaining quota

Subscribd::entitlements()->for($user)->limitOf('projects');          // int|null (null = unlimited)
Subscribd::entitlements()->for($user)->remaining('projects', $user); // int|null
remaining() subtracts the billable’s current usage (from the subscribd_feature_usage table) from the plan limit. Pass the billable as the second argument so Subscribd can look up recorded usage for the correct model.

​
Aggregating across multiple subscriptions

When a user holds multiple named subscriptions, use forAll() to aggregate entitlements across all active slots: 
Subscribd::entitlements()->forAll($user)->allows('reports');    // true if any plan grants it
Subscribd::entitlements()->forAll($user)->limitOf('reports');   // sum of limits; null if any is unlimited
forAll() uses a “most permissive wins” strategy: if any active subscription grants a feature, allows() returns true. For numeric limits, the values are summed — unless any plan has null (unlimited), in which case the result is also null.

​
FeatureMap: using model classes and aliases as keys

Feature keys are not limited to plain strings. Register model class names and aliases in AppServiceProvider::boot() to use them interchangeably: 
use Pixelworxio\Subscribd\Pricing\FeatureMap;

app(FeatureMap::class)
    ->map(Report::class, 'reports')
    ->alias('report', 'reports');
After registration, all three of the following are equivalent: 
Subscribd::entitlements()->for($user)->allows('reports');
Subscribd::entitlements()->for($user)->allows(Report::class);
Subscribd::entitlements()->for($user)->allows('report');
Map your Eloquent model class names to feature keys so you can pass Report::class directly from a controller or policy without remembering the string key.

​
Tracking feature usage

For features with numeric limits, record consumption using the TrackFeatureUsage action. This is distinct from metered billing (which uses RecordUsage for gateway reporting) — feature usage tracking is local and used only for entitlement checks. 
use Pixelworxio\Subscribd\Actions\TrackFeatureUsage;

app(TrackFeatureUsage::class)->increment($user, 'reports');
app(TrackFeatureUsage::class)->increment($user, Report::class, 5);
app(TrackFeatureUsage::class)->decrement($user, 'reports');
app(TrackFeatureUsage::class)->reset($user, 'reports');
app(TrackFeatureUsage::class)->used($user, 'reports'); // int — current period usage
Usage is stored per billing period and scoped to the current period automatically. All used() reads reflect consumption since the start of the subscriber’s current billing cycle.
TrackFeatureUsage is for counting access to plan-limited features (e.g., how many reports a user has generated). For metered billing — where usage drives the invoice amount — use the RecordUsage action instead.

​
Complete gating example

Here is a full controller method that checks entitlement, enforces a limit, records usage, and returns a 403 when the quota is exhausted: 
use Pixelworxio\Subscribd\Actions\TrackFeatureUsage;
use Pixelworxio\Subscribd\Facades\Subscribd;

public function store(Request $request)
{
    $ent = Subscribd::entitlements()->for($request->user());

    // Gate: feature must be enabled on the current plan
    abort_unless($ent->allows('reports'), 403);

    // Enforce limit: remaining() returns null for unlimited
    $remaining = $ent->remaining('reports', $request->user());
    abort_unless($remaining === null || $remaining > 0, 403);

    // Record the usage so remaining() reflects the new count
    app(TrackFeatureUsage::class)->increment($request->user(), 'reports');

    // ... create the report
}