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

# Metered Billing

> Pay-as-you-go billing based on tracked consumption

# Metered Billing

Metered billing (also called usage-based billing) charges customers based on what they actually consume during a billing period. The charge is calculated and billed in arrears at the end of each period. This works well for API products, cloud services, or anything where consumption varies significantly between customers.

## Plan configuration

Use the `metered` pricing rule:

```php theme={null}
// config/subscribd.php
'plans' => [
    'compute' => [
        'name'           => 'Compute',
        'description'    => 'Pay for what you use. Billed monthly in arrears.',
        'rule'           => 'metered',
        'amount'         => 0,           // no base charge; usage drives the bill
        'currency'       => 'USD',
        'interval'       => 'month',
        'interval_count' => 1,
        'rule_config'    => [
            'unit_price' => 2,           // $0.02 per unit
        ],
        'features'       => ['compute_units' => null],
    ],
],
```

`unit_price` is in minor currency units (2 cents per unit in the example above).

## Creating a metered subscription

```php theme={null}
use Pixelworxio\Subscribd\Actions\CreateSubscription;
use Pixelworxio\Subscribd\Models\Plan;

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

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

Because the base `amount` is `0`, no charge is collected upfront.

## Reporting usage

Report consumption with the `RecordUsage` action. Call it at the end of a job, request batch, or any discrete unit of work:

```php theme={null}
use Pixelworxio\Subscribd\Actions\RecordUsage;

app(RecordUsage::class)->execute(
    $subscription->items->firstWhere('key', 'compute_units'),
    $unitsConsumed,
    idempotencyKey: $jobId,   // prevents duplicate records on retries
);
```

The `idempotencyKey` parameter ensures that if your job is retried, the same usage is not counted twice.

## Reading current period usage

```php theme={null}
$item = $subscription->items->firstWhere('key', 'compute_units');

$item->usageThisPeriod();   // int — units recorded since period start
$item->usageSummary();      // collection of UsageRecord models
```

## Billing

At the end of the billing period, Subscribd multiplies total reported units by the `unit_price` to produce the invoice amount. The invoice is charged to the customer's payment method and a new usage period begins.

For gateways with native metered billing support (Stripe), usage records are synced to the gateway and billing is handled by the provider. For other gateways, Subscribd calculates the amount locally and issues the invoice directly.

## Combining metered usage with a base fee

Add a non-zero `amount` to charge a fixed monthly base fee on top of the usage charge:

```php theme={null}
'compute_with_base' => [
    'name'        => 'Compute (with base)',
    'rule'        => 'metered',
    'amount'      => 2000,   // $20.00/month base
    'rule_config' => [
        'unit_price' => 2,   // plus $0.02 per unit
    ],
    // ...
],
```

## Next steps

* **[Tiered Billing](/billing-scenarios/tiered)** — Volume discount thresholds
* **[Plans](/getting-started/plans)** — Full plan configuration reference