github shopperlabs/shopper v3.0.0-rc.9

pre-releaseone hour ago

Important

This is the ninth release candidate of Shopper 3.0. It is a security release: the files of virtual products are no longer publicly downloadable, and two concurrent checkouts can no longer both reserve the last unit of a product on MySQL. It also adds pending refunds and idempotency keys to the payment layer, and fixes the install problems found on a fresh Laravel 13 app. Upgrade from any earlier 3.0 release candidate, and run php artisan migrate.

Installation

"minimum-stability": "RC",
"prefer-stable": true
composer require shopper/framework:^3.0.0-rc

Highlights

Virtual product files are delivered through temporary signed links

The files of a virtual product were stored on the public disk, and the Store API returned their permanent URL in the files attribute of every product payload. Anyone could download a paid file without buying it.

The files collection now lives on a private disk, set by the shopper.media.storage.files_disk key (default local). In the catalog, files only carries id, name, extension and size. A customer gets a file through:

GET /store/customers/me/orders/{orderId}/items/{itemId}/files/{fileId}

The answer is { data: { url, expires_at } } with a link valid for 5 minutes. The order must belong to the customer and Order::allowsDownloads() must be true (payment status Paid or PartiallyRefunded), otherwise the route answers 403. On an s3 disk the link is a presigned URL of the bucket. On any other disk it is the signed route shopper.store.files.download, which streams the file. Guest orders have no download route.

With the SDK:

const { url, expires_at } = await shopper.customer.fileLink(orderId, itemId, fileId)

A file downloads under the name set in the admin panel followed by its extension. Deleting a product now deletes its media through the model, so the files leave the disk with the rows.


Pending refunds and idempotency keys

A payment driver could only answer a refund as done or refused. A provider that accepts a refund and gives its outcome later by webhook had no way to say so, and a refund whose answer was lost could be issued twice.

A driver can now answer PaymentResult::pendingRefund(...) with the provider's refund id. The refund is journalized as Pending and counts against the refundable balance. WebhookAction::Refunded settles it. The new WebhookAction::RefundFailed marks it failed, gives its amount back to the balance and restores the payment status.

PaymentProcessingService::refund() takes a fifth optional argument, $idempotencyKey, stored in the new payment_transactions.idempotency_key column, unique per order. Repeating a key with the same amount returns the refund on file without calling the provider. Repeating it with another amount throws a PaymentException.

$result = $processing->refund($order, $reference, 2500, 'Damaged item', idempotencyKey: 'return-4821');

shopper:payments:reconcile --pull now also settles refunds left pending past --minutes, through the new optional RetrievesRefunds contract. The Stripe driver implements it, and a driver without the contract is left alone.

refund() holds the order lock across the provider call, so call it outside an open database transaction.


Security

Oversell race in stock reservation on MySQL (#702). Two concurrent checkouts could both reserve the last unit of a product. Under repeatable read, the second checkout waited for the product lock, then read the stock level from the snapshot taken before the wait, and reserved stock that was gone. HasStock::stockInventory() now reads the committed level with a lock when the connection is inside a transaction. PostgreSQL was not affected. Reported by adamyordan.

Paid files of virtual products (#697, #698). See the first highlight. Run shopper:files:secure to move files uploaded before this release off the public disk.


Upgrading

composer update "shopper/*" -W
php artisan migrate
php artisan shopper:link --force
php artisan shopper:files:secure

php artisan shopper:upgrade runs the last three for you.

Two payment migrations were added:

  • 2026_11_18_000001_add_idempotency_key_to_payment_transactions_table
  • 2026_11_18_000002_add_type_status_index_to_payment_transactions_table
Change Who is affected What to do
Panel assets are linked at public/vendor/shopper instead of public/{prefix} Every store Run php artisan shopper:link --force. It removes the old public/{prefix} link and runs storage:link
The files collection of products uses the private shopper.media.storage.files_disk disk (default local) Stores selling virtual products Run php artisan shopper:files:secure
files in the Store API product payload only carries id, name, extension and size Storefronts reading file URLs from the catalog Use the order file route or customer.fileLink()
Shopper\Core\Models\Contracts\Order gains allowsDownloads() Custom Order models that implement the contract without extending the core model Add the method
WebhookAction gains the RefundFailed case, and a refund result can be pending Custom payment drivers and listeners with an exhaustive match on the enum Handle the new case, and do not treat a pending result as refunded
The Stripe driver handles refund.failed Stores using Stripe Add the refund.failed event to your webhook endpoint in the Stripe dashboard
orders.generator.start_sequence_from defaults to 0 and is an offset added to the order id Stores that have not published config/shopper/orders.php Set it to 1 in your published config. With 0, the first order placed after the upgrade gets the sequence of the last one placed before it
gehrisandro/tailwind-merge-laravel is replaced by gehrisandro/tailwind-merge-php, and Filament is required at ^5.11 Apps calling the old package directly Require it yourself if you used it

Features

  • feat(payment): add pending refunds and caller idempotency keys by @mckenziearts in #699

Bug Fixes

  • fix(stock): read the committed stock level when reserving inside a transaction by @mckenziearts in #702
  • fix(api): deliver the files of virtual products through temporary signed links by @mckenziearts in #697
  • fix(api): name virtual product downloads after the file and delete media files with the product by @mckenziearts in #698
  • fix(payment): report failed orphan refunds and pull pending refunds by @mckenziearts in #701
  • fix(admin): address the 3.x install feedback and link panel assets at public/vendor/shopper by @mckenziearts in #696
  • fix(admin): point the setup guide Stripe link to the payments docs page by @mckenziearts in #700

Install and dashboard fixes in #696

  • composer require shopper/framework no longer fails without -W on a fresh Laravel 13 app.
  • shopper:user stops with a hint to run AuthTableSeeder when the administrator role is missing.
  • The installer prints the real login URL.
  • Variant sales are now counted for the parent product in the top selling products.
  • The revenue card shows the month to date, and is labelled "Revenue this month".
  • Site, documentation and Discord links move to shopperphp.com.

Contributors

@mckenziearts

Thanks to adamyordan for reporting the stock reservation race.

Full Changelog: v3.0.0-rc.8...v3.0.0-rc.9

Don't miss a new shopper release

NewReleases is sending notifications on new releases.