Skip to main content

​
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: 
// 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

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

$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: 
'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