← Posts

Simple Commerce v5 released!

April 28th, 2023 - 3 min read

I've just tagged the latest release of Simple Commerce, version 5. It includes a new concept of order & payment statuses, now supports Stripe Payment Elements out of the box, improves developer experience around building custom gateways & adds support for Statamic 4.

It's come a long way since it was released back in 2020. Let's dive into some of the big new features!

Order & Payment statuses

Previously, orders had a couple of status toggles, like Is Paid & Is Shipped. Depending on how the toggles were toggled an order was either: cart/paid/shipped/refunded.

However, after various discussions with customers, it became clear that we should probably introduce two new concepts: Order Statuses & Payment Statuses.

The Order Status represent the 'state' of the order, either Cart/Placed/Dispatched/Cancelled.

The Payment Status represents the 'state' of the order's payment, either Unpaid/Paid/Refunded.

Decoupling the statuses means an order can be placed however not necessarily paid (for example: if you're waiting for a manual bank transfer to go through).

Both of the statuses have their own fields within orders to let your back-office staff see where they're at. The statuses can also be updated within the Control Panel via an action.


Existing orders will be migrated to the new format during the upgrade process.

Stripe Payment Elements support

Simple Commerce now takes advantage of Stripe's relatively new Payment Elements functionality. This means you can now let customers pay using payment methods other than their credit/debit card.

Stripe will localise the payment methods displayed depending on the customer's location. You can also use this to let customers pay with services like Klarna. You just need to enable them within your Stripe Dashboard.


The Payment Elements is the default for new Simple Commerce sites starting today!

If you wish to switch to it on an existing site, you'll want to copy the Stripe code from the Starter Kit into your site & also configure the Stripe webhook so Simple Commerce knows when payments have gone through successfully.

Improved developer experience (DX) around building custom gateways

These changes are zero-impact to most sites, unless you maintain your own custom payment gateway for Simple Commerce.

I've chosen this as a good time to rename some of the methods used when implementing custom gateways & various other changes in terms of what's returned by methods, like prepare and purchase.

For a full overview of what's changed in relation to the Payment Gateway DX changes, review the pull request.

Statamic 4 Support

Simple Commerce now supports Statamic 4, which was released in the last couple of days. In fact, Simple Commerce v5 only supports Statamic 4, it doesn't support 3.3 or 3.4.

In addition, PHP 8.2 and Laravel 10 are the only supported versions of PHP & Laravel.

Lots more....

There's lots of other things also included in Simple Commerce v5:

You may view a full list of all the changes in the changelog.

To update your site, follow the instructions in the v4.x to v5.x Upgrade Guide. You may create new sites using the Starter Kit.