Stripe Billing Integration for SaaS Subscriptions

Stripe Billing Integration for SaaS Subscriptions

Stripe Billing is the most complete ready-made billing implementation for SaaS on the market. Covers subscriptions, trial periods, upgrades/downgrades, prorated billing, metered consumption, automatic retry on failure. Implementation from scratch would take months — Stripe Billing reduces it to 1–2 weeks.

Key Entities

Product → Price → Subscription → Invoice → PaymentIntent. Product is a plan (Basic, Pro, Enterprise). Multiple Prices are attached to product — monthly and yearly. Subscription links customer to Price. Invoice is issued automatically at start of each period.

Creating Products and Prices

// Create product (once during setup)
$product = \Stripe\Product::create([
    'name'     => 'Pro Plan',
    'metadata' => ['plan_id' => 'pro'],
]);

// Monthly price
$monthlyPrice = \Stripe\Price::create([
    'product'       => $product->id,
    'unit_amount'   => 2900,  // $29.00
    'currency'      => 'usd',
    'recurring'     => ['interval' => 'month'],
    'lookup_key'    => 'pro_monthly', // to find without storing ID
]);

// Annual (with discount)
$yearlyPrice = \Stripe\Price::create([
    'product'       => $product->id,
    'unit_amount'   => 27900, // $279.00
    'currency'      => 'usd',
    'recurring'     => ['interval' => 'year'],
    'lookup_key'    => 'pro_yearly',
]);

User Registration and Subscription Creation

// On registration — create Stripe Customer
$stripeCustomer = \Stripe\Customer::create([
    'email'    => $user->email,
    'name'     => $user->name,
    'metadata' => ['user_id' => $user->id],
]);
$user->update(['stripe_customer_id' => $stripeCustomer->id]);

// Create subscription with trial
$subscription = \Stripe\Subscription::create([
    'customer'          => $user->stripe_customer_id,
    'items'             => [['price' => 'pro_monthly']],
    'trial_period_days' => 14,
    'payment_behavior'  => 'default_incomplete',
    'payment_settings'  => ['save_default_payment_method' => 'on_subscription'],
    'expand'            => ['latest_invoice.payment_intent'],
]);

// Return client_secret for card confirmation on frontend
$clientSecret = $subscription->latest_invoice->payment_intent->client_secret;

payment_behavior: default_incomplete means subscription is created but activated only after successful first payment. Important for free trials: card is linked but not charged.

Upgrade/Downgrade

public function changePlan(User $user, string $newPriceLookupKey): void
{
    $prices = \Stripe\Price::all(['lookup_keys' => [$newPriceLookupKey]]);
    $newPrice = $prices->data[0];

    $subscription = \Stripe\Subscription::retrieve($user->stripe_subscription_id);

    \Stripe\Subscription::update($subscription->id, [
        'items'              => [[
            'id'    => $subscription->items->data[0]->id,
            'price' => $newPrice->id,
        ]],
        'proration_behavior' => 'create_prorations', // or 'none' for annual
        'billing_cycle_anchor'=> 'unchanged',
    ]);
}

On upgrade with proration, Stripe automatically credits unused time of current plan and issues invoice for the difference.

Webhook: Status Synchronization

All business logic should be built on webhooks, not synchronous API responses. Events to handle:

protected array $handlers = [
    'customer.subscription.created'       => 'onSubscriptionCreated',
    'customer.subscription.updated'       => 'onSubscriptionUpdated',
    'customer.subscription.deleted'       => 'onSubscriptionCancelled',
    'invoice.payment_succeeded'           => 'onInvoicePaid',
    'invoice.payment_failed'              => 'onInvoicePaymentFailed',
    'customer.subscription.trial_will_end'=> 'onTrialEndingSoon',
];

public function onInvoicePaymentFailed(array $event): void
{
    $subscription = $event['data']['object']['subscription'];
    $user = User::where('stripe_subscription_id', $subscription)->firstOrFail();

    // Don't block immediately — Stripe does retry
    // next_payment_attempt in invoice
    $nextRetry = $event['data']['object']['next_payment_attempt'];
    Notification::send($user, new PaymentFailedNotification($nextRetry));
}

Customer Portal

Stripe Customer Portal is ready UI to manage subscription (change card, cancel, invoice history). No need to write from scratch:

$session = \Stripe\BillingPortal\Session::create([
    'customer'   => $user->stripe_customer_id,
    'return_url' => route('dashboard'),
]);
return redirect($session->url);

Configured in Stripe Dashboard: allow/disallow plan change, cancellation, invoice download.

Metered Billing

For SaaS with consumption-based pricing (API calls, storage, users):

// Price with metered billing
$price = \Stripe\Price::create([
    'product'   => $product->id,
    'currency'  => 'usd',
    'recurring' => [
        'interval'       => 'month',
        'usage_type'     => 'metered',
        'aggregate_usage'=> 'sum',
    ],
    'billing_scheme' => 'per_unit',
    'unit_amount'    => 1, // $0.01 per unit
]);

// Report consumption (once per hour or end of period)
\Stripe\SubscriptionItem::createUsageRecord(
    $subscriptionItemId,
    ['quantity' => $apiCallsThisPeriod, 'action' => 'set']
);

action: set sets absolute value, increment adds to current. set is safer on retry.