v5.0: Order & Payment Statuses

[duncanmcclean]

This pull request changes the way Simple Commerce decides on the "status" of orders.

At the moment, orders have two status related fields: is_paid and is_shipped. They're two boolean fields that decide if an order has been marked as paid / has been marked as shipped.

After a conversation in a discussion a few months ago, someone asked for a 'middle state' between an order being considered a "cart" and being considered as "paid" (their use case was a Bank Transfer payment gateway).

After some thinking, I decided to refactor how order & payment statuses work (hence this PR!). This will be released as part of v5.0, the next big version of SC.

New Statuses

The plan is to create two new status concepts: Order Status & Payment Status. They'll both have different states:

• Order Status

  • Cart
  • Placed
  • Dispatched (renamed from Shipped)
  • Cancelled

• Payment Status

  • Unpaid
  • Paid
  • Refunded

Lifecycle

When an order is initially created, it will be a Cart and Unpaid.

After a customer has submitted the checkout form or redirected back from a third-party gateway, their order will be marked as Placed.

Their order will then only be marked as Paid when we receive confirmation from the payment gateway that a payment has taken place & been successful.

In the Control Panel, admins can then mark orders as Dispatched or as Cancelled. They may also Refund orders.

Status Log

When the status of an order changes, the status change will be logged in the order's "status log". You can see the timestamp that the order was set to any of the different statuses.

status_log:
  paid: '2023-02-06 20:11'
  placed: '2023-02-06 20:11'

Migration

As part of the update to v5.0, a few update scripts will be run for you: one which updates your order blueprint to remove old fields & add the new ones, one which updates your notification config (order_shipped -> order_dispatched) and a final one to actually migrate existing orders.

If you keep all of your orders in version control, then you shouldn't need to take any action, apart from actually updating.

However, if you have Git-ignored your orders OR you're storing your orders in a database, you'll need to run this command after deploying the update:

php please sc:migrate-order-statuses

This command will take your existing orders and update them to match the new order status format.

Database Orders

A few things to take note of when doing the update with database orders:

• When you run the sc:migrate-order-statuses command, Simple Commerce will generate a migration containing the new columns. It'll also run your migrations for you.
• The 'old' order status columns will be kept in your database for now & will be set to their default values. These columns will be removed as part of the v6.0 update process.

[github-actions[bot]]

Released as part of v5.0.0.