Skip to main content

​
Tiered Billing

Tiered billing applies different per-unit rates depending on how much of a resource is consumed. Higher volumes unlock lower unit prices, encouraging growth while rewarding scale. Subscribd implements graduated tiering: each tier’s rate applies only to the portion of units within that tier’s range. A flat fee can optionally be added when a tier is reached.

​
Plan configuration

Use the tiered pricing rule: 
// config/subscribd.php
'plans' => [
    'api_tiered' => [
        'name'           => 'API (Tiered)',
        'rule'           => 'tiered',
        'amount'         => 0,           // base price; tier amounts drive the bill
        'currency'       => 'USD',
        'interval'       => 'month',
        'interval_count' => 1,
        'rule_config'    => [
            'tiers' => [
                // up_to: null means "remainder / infinite"
                ['up_to' =>  1000, 'unit_amount' => 5,  'flat_amount' =>     0],
                ['up_to' => 10000, 'unit_amount' => 3,  'flat_amount' =>  2000],
                ['up_to' =>  null, 'unit_amount' => 1,  'flat_amount' =>  5000],
            ],
        ],
        'features' => ['api_calls' => null],
    ],
],
All amounts are in minor currency units (cents for USD). unit_amount is per-unit cost in cents. flat_amount is a fixed fee charged when the tier is reached.

​
How graduated tiers are calculated

For 12,000 API calls with the configuration above:
TierUnitsUnit priceSubtotal
Tier 1 (1–1,000)1,000$0.05$50.00
Tier 2 (1,001–10,000)9,000$0.03$270.00
Tier 3 (10,001–∞)2,000$0.01$20.00
Flat fee (Tier 3 reached)——$50.00
Total$390.00

​
Reporting usage for tiered plans

Tiered plans are typically paired with usage reporting. Report consumption during the billing period: 
use Pixelworxio\Subscribd\Actions\RecordUsage;

app(RecordUsage::class)->execute(
    $subscription->items->firstWhere('key', 'api_calls'),
    $callsThisBatch,
    idempotencyKey: $requestId,
);
Usage is summed at the end of each billing period and the tiered calculation is applied to produce the invoice.

​
Creating a tiered subscription

use Pixelworxio\Subscribd\Actions\CreateSubscription;
use Pixelworxio\Subscribd\Models\Plan;

$plan = Plan::query()->where('key', 'api_tiered')->firstOrFail();

app(CreateSubscription::class)->execute($user, $plan);

​
Next steps