[16.x] Stripe Basil API Support

[Diddyy]

This PR targets the 16.x branch in line with Laravel’s support policy. It finalizes Cashier’s compatibility with Stripe’s Basil API (API version 2025-03-31.basil), as highlighted in the Cashier source code:

// src/Cashier.php
const STRIPE_VERSION = '2025-03-31.basil';

Summary of Changes

Invoice Line Items: Added helpers to extract pricing data using Stripe’s new price_details and inline_price_data structures introduced in Basil:

public function priceId()
{
    // Handle the new pricing structure (Basil release)
    if (isset($this->item->pricing) && $this->item->pricing->type === 'price_details') {
        return $this->item->pricing->price_details->price ?? null;
    }

    return null;
}

Unit Amount Handling: Retrieve unit amounts and support inline price data:

public function unitAmount()
{
    // Handle the new pricing structure (Basil release)
    if (isset($this->item->pricing)) {
        if (isset($this->item->pricing->unit_amount_decimal)) {
            return (int) $this->item->pricing->unit_amount_decimal;
        }
        if ($this->item->pricing->type === 'inline_price_data' &&
            isset($this->item->pricing->inline_price_data->unit_amount)) {
            return (int) $this->item->pricing->inline_price_data->unit_amount;
        }
    }

    return null;
}

Tax Behavior Retrieval: Access the tax_behavior on invoice line items:

public function taxBehavior()
{
    $price = $this->price();
    return $price ? ($price->tax_behavior ?? null) : null;
}

Benefits to Users

Keeps Cashier aligned with Stripe’s latest Basil API, as requested by Taylor April tweet inviting contributions.

Testing

Added PHPUnit tests covering the new invoice line item helpers:

priceId and price retrieval
unitAmount handling for both price_details and inline_price_data
taxBehavior method

All test suites pass locally. Please refer to the CI checks for confirmation.

Motivation

Taylor mentioned that the team “would love some assistance making Cashier compatible with Stripe's latest API version (Basil)” — this PR answers that call. It updates core invoice item logic and tests to ensure developers can rely on Cashier when using the latest Stripe features.

This is my first significant open source contribution attempt so apologies if it isn't quite up to scratch, I welcome any criticism or commits to improve it!

[driesvints]

Thank you. I'll review this one when I find some time.