[12.x] Metered billing

[driesvints]

This PR adds support for Metered Billing. Thanks to @benjamindoe

Closes #555

Usage

Subscribe user to metered plan:

$subscription = $user->newSubscription('main', [])
    ->meteredPlan('pro-plan')
    ->create('pm_card_visa');

Reporting usage from the subscription:

$user->subscription('default')->reportUsage(); // defaults to quantity of 1
$user->subscription('default')->reportUsage(10);
$user->subscription('default')->reportUsageFor('pro-plan', 10);

Reporting usage from a subscription item:

$item = $$user->subscription('default')->findItemOrFail('pro-plan');

$item->reportUsage();
$item->reportUsage(10);

Stripe gives you the ability to update a usage record at a particular timestamp. The reportUsage & reportUsageFor methods accept a Carbon object to specify the timestamp:

$subscription->reportUsage(100, now()->subHour());
$subscription->reportUsageFor('pro-plan', 100, now()->subHour());

// Or report for a specific subscription item...
$item->reportUsage(100, now()->subHour());

Todos

• Reporting usage
• Fetching usage records
• Swapping behavior
• Cancelling subscriptions
• Stripe Checkout integration
• Tests

Related Stripe Documentation

• https://stripe.com/docs/billing/subscriptions/metered-billing
• https://stripe.com/docs/billing/subscriptions/metered
• https://stripe.com/docs/api/usage_records
• https://stripe.com/docs/api/subscriptions/update#update_subscription-items-clear_usage

[driesvints]

@benjamindoe I'm finally done with the PR! Can you give it a review?

[taylorotwell]

What does this do?

[driesvints]

Clearing usage for a metered plan is required when the plan is deleted. Stripe has noted that this param will probably be removed in the future and the behavior would be the default.