> ## Documentation Index
> Fetch the complete documentation index at: https://spark.laravel.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrade

> Learn how to upgrade your Spark Stripe application.

## Upgrading to Spark (Stripe) 6.0 From 5.x

Spark (Stripe) 6.0 primarily provides an upgrade from Cashier 15.x to Cashier 16.x. As such, in addition to the upgrade guide below, please consult the [Cashier 16 upgrade guide](https://github.com/laravel/cashier-stripe/blob/16.x/UPGRADE.md).

### Stripe API Version

The default Stripe API version for Cashier 16 is `2025-07-30.basil`. If this is the latest Stripe API version when you upgrade to this Cashier version, then we recommend you also upgrade your Stripe API version settings in your Stripe dashboard to this version after deploying the Cashier upgrade. If this is no longer the latest Stripe API version, we recommend you do not modify your Stripe API version settings.

Older Stripe accounts (e.g., those created before Basil previews) may encounter compatibility issues with Basil billing APIs or require manual API key upgrades in the Stripe dashboard. We recommend testing in a staging environment, as some legacy features might not migrate seamlessly. Note that `StripeApiVersion::CURRENT` is used internally, so the exact version could evolve with minor Cashier releases — lock your dashboard version post-upgrade to avoid drift.

If you use the Stripe SDK directly, make sure to properly test your integration after updating.

### Database Migration Changes

To better track usage-based billings, we've added `meter_event_name` and `meter_id` to the `subscription_items` table. The `meter_id` column is `nullable` and is cast as a string in the model.

If you have custom queries or indexes on `subscription_items`, consider adding them for these fields. Additionally, internal ID generation has changed from `uniqid()` to `Str::uuid()`, which is unlikely to affect user code but could impact extensions relying on prefix-based uniqueness.

To update your database schema, you should run the following commands:

```shell theme={null}
php artisan vendor:publish --tag="spark-migrations"

php artisan migrate
```

## Upgrading to Spark (Stripe) 5.0 From 4.x

Spark (Stripe) 5.0 primarily provides an upgrade from Cashier 14.x to Cashier 15.x. As such, in addition to the upgrade guide below, please consult the [Cashier 15 upgrade guide](https://github.com/laravel/cashier-stripe/blob/15.x/UPGRADE.md).

### Stripe API Version

The default Stripe API version for Cashier 15.x is `2023-10-16`.

If you use the Stripe SDK directly, make sure to properly test your integration after updating.

#### Upgrading Your Stripe Webhook

<Note>
  It's very important that you upgrade your webhook immediately after updating and deploying Spark in order to minimize conflicts where the API version of your webhook does not match the version used by Cashier.
</Note>

You should ensure your Stripe webhook operates on the same API version as Spark's underlying API version used by Cashier. To do so, you may use the `cashier:webhook` command from your production environment to create a new webhook that matches Cashier's Stripe API version. Of course, you should ensure the webhook's URL corresponds to the URL where your application expects to receive webhook requests. By default, your application will receive Spark Stripe webhooks at `/spark/webhook`:

```bash theme={null}
php artisan cashier:webhook --disabled --url "https://your-site.com/spark/webhook"
```

This command will create a new webhook with the same Stripe API version as Cashier [in your Stripe dashboard](https://dashboard.stripe.com/webhooks). The webhook will be immediately disabled so it doesn't interfere with your existing production application until you are ready to enable it.

You may use the following upgrade checklist to properly enable to the new webhook:

1. If you have webhook signature verification enabled, disable it on production by temporarily removing the `STRIPE_WEBHOOK_SECRET` environment variable.
2. Add any extra Stripe events your application requires to the new webhook in your Stripe dashboard.
3. Disable the old webhook in your Stripe dashboard.
4. Enable the new webhook in your Stripe dashboard.
5. Re-enable the new webhook secret verification by re-adding the `STRIPE_WEBHOOK_SECRET` environment variable in production with the secret from the new webhook.
6. Remove the old webhook in your Stripe dashboard.

After following this process, your new webhook will be active and ready to receive events.

### Publishing Migrations

Spark Stripe 5.0 no longer automatically loads migrations from its own migrations directory. Instead, you should run the following command to publish Spark's migrations to your application:

```bash theme={null}
php artisan vendor:publish --tag=spark-migrations
```

### Receipts Table Deprecation

While the `receipts` table contains historical data that may be valuable for reference, it is no longer used and can be safely removed.

### Receipts Renamed to Invoices

Code and text throughout Spark Stripe has been updated to refer to "receipts" as "invoices". This is to bring Spark Stripe closer to Stripe's own terminology for this concept. To accomodate this, you should make the following changes to your application:

First, rename the corresponding feature flag in your `spark.php` config:

```php theme={null}
// From...
Features::receiptEmails(['custom-addresses' => true]),

// To...
Features::invoiceEmails(['custom-addresses' => true]),
```

Then, rename the `receipt_data` key in your application's `config/spark.php` configuration file to `invoice_data`:

```php theme={null}
// From...
'receipt_data' => [
    'vendor' => 'Your Product',
    'product' => 'Your Product',
    'street' => '111 Example St.',
    'location' => 'Los Angeles, CA',
    'phone' => '555-555-5555',
],

// To...
'invoice_data' => [
    'vendor' => 'Your Product',
    'product' => 'Your Product',
    'street' => '111 Example St.',
    'location' => 'Los Angeles, CA',
    'phone' => '555-555-5555',
],
```

Next, if you have published Spark's views using the `vendor:publish` Artisan command, you should rename the `receipt.blade.php` template to `invoice.blade.php` in your application's `resources/views/vendor/spark/mail` directory.

Lastly, create a migration to rename the `user` table's `receipt_emails` column to `invoice_emails`:

```php theme={null}
Schema::table('users', function (Blueprint $table) {
    $table->renameColumn('receipt_emails', 'invoice_emails');
});
```