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": truecomposer require shopper/framework:^3.0.0-rcHighlights
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:securephp artisan shopper:upgrade runs the last three for you.
Two payment migrations were added:
2026_11_18_000001_add_idempotency_key_to_payment_transactions_table2026_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/frameworkno longer fails without-Won a fresh Laravel 13 app.shopper:userstops with a hint to runAuthTableSeederwhen 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
Thanks to adamyordan for reporting the stock reservation race.
Full Changelog: v3.0.0-rc.8...v3.0.0-rc.9