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

[kyranb]

@driesvints

Is there a rough target release date for Cashier 16/Basil support?

[Diddyy]

I feel like its been draft for too long. I have done all I personally can on it so any further suggestions I will implement but apart from that I feel like it would be ace to get the ball rolling on this being merged! @driesvints

[taylorotwell]

@crynobone could you do a bullet point list upgrade guide of what users the steps users will need to take to upgrade?

[Diddyy]

@crynobone @taylorotwell @driesvints Whats currently holding this back? Keen to see it merged :)

[taylorotwell]

Is this supposed to be &&?

[taylorotwell]

@Diddyy merged, but I have no idea how to update the docs for this, and also need an upgrade guide.

[kyranb]

Thanks @taylorotwell for merging.

One other thing to flag perhaps before this gets a tagged release. It seems that as part of the basil release, Stripe are moving towards a new "flexible" billing mode.

https://docs.stripe.com/billing/subscriptions/billing-mode
https://docs.stripe.com/changelog/basil/2025-06-30/billing-mode
https://docs.stripe.com/billing/subscriptions/billing-mode?dashboard-or-api=api&lang=php
https://docs.stripe.com/api/subscriptions/create#create_subscription-billing_mode

While it's possible to pass in the 'billing_mode' when creating a new subscription/checkout like so

$user->newSubscription('default', $priceId)
      ->create(null, [], [
          'billing_mode' => ['type' => 'flexible']
      ]);

I'm wondering if it's worth having a config option and/or a helper method on the SubscriptionBuilder

i.e

'cashier' => [
          'default_billing_mode' => env('CASHIER_DEFAULT_BILLING_MODE', 'classic'),
      ],

or

  class SubscriptionBuilder
  {
      /**
       * The billing mode for the subscription.
       *
       * @var array|null
       */
      protected $billingMode = null;

      /**
       * Set the billing mode for the subscription.
       *
       * @param  string  $type
       * @return $this
       */
      public function withBillingMode(string $type = 'flexible')
      {
          $this->billingMode = ['type' => $type];
          return $this;
      }

      /**
       * Get the default billing mode from config.
       *
       * @return string
       */
      protected function getDefaultBillingMode(): string
      {
          return config('cashier.default_billing_mode', 'classic');
      }

      /**
       * Get the effective billing mode for this subscription.
       *
       * @return string
       */
      protected function getEffectiveBillingMode(): string
      {
          if ($this->billingMode) {
              return $this->billingMode['type'];
          }

          return $this->getDefaultBillingMode();
      }

      /**
       * Get the billing mode for the Stripe payload.
       *
       * @return array|null
       */
      protected function getBillingModeForPayload()
      {
          $mode = $this->getEffectiveBillingMode();

          // Only include billing_mode if it's not classic (Stripe's default)
          if ($mode !== 'classic') {
              return ['type' => $mode];
          }

          return null;
      }
      

What do you think? @taylorotwell @driesvints @crynobone

[Diddyy]

@Diddyy merged, but I have no idea how to update the docs for this, and also need an upgrade guide.

@crynobone is this something you're able to help with? :)

[crynobone]

@Diddyy I'm going through the upgrading guide, and we did face some issues, especially dealing with v2 specific API on an old Stripe account (old API keys and API versions).

https://docs.stripe.com/api-v2-overview?api-version=2025-07-30.preview&rds=1#limitations

We need to be able to list all the required steps to upgrade to the new version.

[crynobone]

Furthermore, new metered billings is not on the PR description.

[Diddyy]

@Diddyy I'm going through the upgrading guide, and we did face some issues, especially dealing with v2 specific API on an old Stripe account (old API keys and API versions).

https://docs.stripe.com/api-v2-overview?api-version=2025-07-30.preview&rds=1#limitations

We need to be able to list all the required steps to upgrade to the new version.

Thanks for checking this @crynobone 🙌

I won’t be able to put together the full upgrade guide myself, but I agree it’s needed to document the steps (API version upgrade, sandbox key requirements, metered billing, etc.). Maybe it makes sense to open a follow-up issue in the relevant repo dedicated to the upgrade guide so we can track that separately?