wt_commerce 1.3.0

# WT Commerce 1.3.0 — release notes

Covers `wt_simple_pay`. Drupal 11, PHP 8.1+. **Run `drush updb -y` after updating** (see Upgrade notes).

## Features

- **Order notes (optional).** Buyers can add a note to their order at checkout, for example delivery instructions. It is off by default: turn it on and choose the field label under *Configuration → Web services → WT Commerce: Payment & Cart Setup → Store UI & GDPR → Order Notes*.
- Plain text, up to 1000 characters; line breaks are kept.
- Saved on the order (new field "Order Notes"), shown on the order page, and included in the admin alert and the buyer's confirmation e-mail.
- Never sent to Viva Wallet, PayPal or Stripe, and never written to the site log.
- Notes can contain personal data. Mention them in your privacy policy; they are deleted together with the order.
- New installs also get a short "Notes" column on the Orders dashboard. Existing dashboards are not changed: add the field in Views if you want it.

- **Delivery methods without a limit of three.** The *Shipping Options* tab now lists your delivery methods in a table: add as many as you need, drag them into the order buyers see, remove one with a tick. Each method gets a fixed ID when it is first saved (your existing options keep the IDs `opt_1`–`opt_3`); you can type your own ID for a new method, otherwise it is made from the title (`method_1`, `method_2`… for titles in Greek or other non-Latin scripts). Titles and descriptions are translatable, and translations stay with their method when you add or remove others.

- **Unpaid bank transfers can be cancelled automatically.** New setting under *Payment methods → Direct Bank Transfer*: "Cancel unpaid orders after (days)". Cron then cancels older unpaid bank-transfer orders (they stay in your order list as *Cancelled*), releases their bookings and, optionally, e-mails the buyer in the language of the order. The e-mail text is editable and translatable. Default: 0 = never, as before.

- **Stock (optional).** Each product gets a **Stock & shipping** tab that first asks how stock is counted: not tracked (the default, so existing products are unchanged), one number for the whole product, or one number per variation (e.g. per size).
- Orders take their units when placed, with any payment method. Cancelled orders give them back; refunded orders do not ("Goods returned" on the Stock & shipping tab when they come back).
- Two buyers can never get the last unit: exactly one order gets it, the other buyer is told it was just sold out.
- Buyers see "sold out" on variations, the *Out of Stock* button when nothing is left, "Only N left" when they ask for more, and the cart blocks checkout until they lower the quantity.
- The Stock & shipping tab shows how many units orders have taken, marks sold-out and low-stock variations, and keeps a history of every change. An editor's save never overwrites a change made by an order in the meantime.
- New permission **Manage WT Commerce stock** for shop staff (not granted automatically); a low stock notice for editors (off by default).
- Product pages update as soon as the stock changes.

- **Shipping classes (optional).** Offer a delivery method only for certain items, for example a parcel locker only for small items. Create classes under *Shipping Options* and tick them on that method; give a product, or a single variation, a class on its Stock & shipping tab. The method then appears as an extra choice when every item in the cart has its class; your other methods stay available. Without classes nothing changes. In the cart, a class-limited method is highlighted, so buyers see the extra choice their items unlocked. Tip: drag it to the top.

- **Free-shipping message (optional).** Under the delivery methods the cart says how much more the buyer needs for free shipping ("Add 12.00 € more to get free shipping."), or that the order qualifies. It uses exactly the check that prices the delivery, and is not shown without a threshold, for bookings-only or digital carts. New installs show it; existing sites can turn it on under *Shipping Options → Show free-shipping message in cart*.

## Bug fixes

- **Full order summary.** The order's "Cart Contents" field is no longer cut to 255 characters, so large orders keep every line. Payment gateways still receive a shortened copy where they require one.

- **Shipping is priced on the server at checkout.** The cart used to keep the delivery *price* in the buyer's session and checkout charged it as it was. Now only the chosen method is kept and checkout prices it again from your current settings, so a price change or a removed method can never be charged wrongly. A buyer whose method was removed in the meantime is asked to choose again.

- **Settings page without the Block or Database Logging module.** The *Payment & Cart Setup* page no longer fails when one of these core modules is disabled.

- **Ready for Drupal 12.** Order status changes no longer read the `original` entity property (deprecated in Drupal 11.2, removed in 12), and the new status report checks use the current hook API.

## Before you start tracking stock

- **Run cron every 5 to 15 minutes** (a server cron job). Abandoned online payments give their units back when cron removes them; Automated Cron only runs on page visits. The status report warns when cron is older than an hour.
- **Bank transfer:** unpaid bank-transfer orders keep their units until you cancel them. Set *Cancel unpaid orders after (days)* (3 to 7 days is a good choice) if you offer bank transfer.
- **Colours and sizes:** stock is counted per variation, not per attribute. See *Stock → Colour and size* in the `wt_simple_pay` README for the two ways to set this up.
- **Staff:** give shop staff *Manage WT Commerce stock* plus edit access to products.
- **Tip:** the existing *Out of Stock* checkbox (`field_wt_out_of_stock`) is now a manual "not for sale" pause that keeps the stock numbers. Consider relabelling it "Not for sale (pause)" in Field UI.

## Upgrade notes

1. Put the site in maintenance mode (`drush state:set system.maintenance_mode 1`), back up the database, update the code (`composer update drupal/wt_commerce`). Maintenance mode is good practice for any update, but the shop no longer breaks if you skip it: until `drush updb` has run, products are simply not stock-tracked (as in 1.2.x), and the *Stock & shipping* tab asks you to run the updates.
2. Run `drush updb -y`. New update hooks:
- `wt_simple_pay_update_8104`: adds the optional "Order Notes" field to orders, shows it on the order form and page, and adds the two new settings (notes stay **off**). It only adds; nothing is removed or overwritten, and running it again changes nothing.
- `wt_simple_pay_update_8105`: moves your delivery options to the new list. Options with a title keep their order, price and description, with the IDs `opt_1`–`opt_3`; empty options are dropped; the old keys are removed. Translations of the option titles and descriptions move to the new methods. Until it has run, checkout keeps offering your old options.
- `wt_simple_pay_update_8106`: creates the stock tables (`wt_product_variant`, `wt_stock_hold`, `wt_stock_log`). No product is stock-tracked until you set a quantity, so existing products stay unlimited.
- `wt_simple_pay_update_8107`: adds the bank-transfer settings above and the low stock notice (both off by default). Nothing changes until you set them.
- `wt_simple_pay_update_8108`: prepares shipping classes (a new column and an empty setting). Nothing changes until you create a class.
- `wt_simple_pay_update_8109`: adds the free-shipping message setting, **off** on existing sites. Turn it on under *Shipping Options* if you want it.
3. `drush cr`, then end maintenance mode (`drush state:set system.maintenance_mode 0`). If you manage configuration in code, export it (`drush cex`): the new field and settings belong to your site's configuration.
4. **Drupal version.** 1.3.0 still runs on every Drupal 11 release (tested on 11.1 and 11.4; see *Tested on* below). The new status report warnings for stock (unpaid bank transfers, cron, translated variations) appear on Drupal 11.2 and later only; on 11.0 and 11.1 they are simply not shown, and everything else works the same.

## Tested on

- Drupal 11.4 (PHP 8.4, MySQL 8.0 and SQLite): automated Unit and Kernel tests, plus manual checkout, stock and shipping tests with Stripe (sandbox), bank transfer and pay later.
- Drupal 11.1.10: the same automated Unit and Kernel tests (96 tests, all passing).
- Upgrade from 1.2.3: a copy of a real 1.2.3 site database, all six update hooks (8104–8109) in one `drush updb`, then the stock, shipping and order-notes checks above. Before `drush updb` on the same copy: product page, cart, bank-transfer checkout, order cancel/reactivate/delete and cron work, with nothing tracked.