> ## Documentation Index
> Fetch the complete documentation index at: https://docs.subscribd.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Tiered Billing

> Volume discounts based on usage thresholds

# 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:

```php theme={null}
// 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:

| Tier                      | Units | Unit price | Subtotal     |
| ------------------------- | ----- | ---------- | ------------ |
| 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:

```php theme={null}
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

```php theme={null}
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

* **[Metered Billing](/billing-scenarios/metered)** — Pay-as-you-go consumption billing
* **[Plans](/getting-started/plans)** — Full plan configuration reference