Requirements and install¶

Loyalty installs like every other extension sold here. Follow the shared procedure rather than a Loyalty-specific one:

Requirements — check these first.
Installing an extension — upload, enable, grant permission. All three steps are required.
Troubleshooting an install — if it did not work.

What is specific to Loyalty¶

The permission entry to tick at step 3 of the shared procedure is:

extension/loyalty/module/loyalty

Tick it under both Access Permission and Modify Permission, for every user group that should be allowed to use Loyalty.

Two screens beside it have entries of their own:

extension/loyalty/customer/personal_data
extension/loyalty/customer/purge

Personal Data, under Customers, looks up, exports and erases what Loyalty holds about one person. Opening it needs Access on its entry; doing anything on it needs Modify on OpenCart's own customer/customer, the permission that already lets somebody edit a customer.
Remove everything held about a person, linked from Loyalty's own screen, needs Access and Modify on its own entry, and the link is absent for a group that cannot open it. What it removes, and what it leaves, is in limits.

Installing grants the last two to your own user group, the one you install with. Any other group has to be ticked by hand, once.

The order total has an entry of its own, for the second half described below:

extension/loyalty/total/loyalty

Access on it opens Extensions › Extensions › Order Totals › Loyalty, and Modify saves it. Installing the order total grants both to your own group, as installing the module does; any other group is ticked by hand.

Nothing is awarded until you say so. Installing leaves the programme switched off, no order status ticked and earning not started. No order earns a point until you press Start awarding points on the Loyalty screen. The one thing that does not wait for that button is the welcome bonus: if you set one, it is paid for every account created while the programme's Status is on. See the quick start.

Two things to install, in this order¶

Loyalty registers two extensions, and a store needs both:

Extensions › Extensions › Modules › Loyalty. Install it, then open it. This is the screen where every decision about the programme is made.
Extensions › Extensions › Order Totals › Loyalty. Install it once the module is configured. It carries a status and a sort order and nothing else; it is the line at checkout that customers spend points through.

The order total cannot be folded into the module: OpenCart only lists an order total that ships a screen of its own, and the checkout only calls an order total that is installed as one.

Configure the module first, switch OpenCart's own Reward Points order total off, and only then install the Loyalty order total. Done the other way round, the store has no working way to spend points for as long as the form takes. While core's total is on, both Loyalty screens say so in a banner and link to it.

What it adds to your store¶

Four tables, all named oc_loyalty_*: one row per points movement, one summary row per customer, a copy of your settings, and the lock the scheduled pass takes on each store. None of them is ever dropped, including when you uninstall.
Rows in OpenCart's own reward table, oc_customer_reward, for every movement: that table is where every customer's balance comes from, so this is what makes Loyalty's points real points on core's screens.
One index on that reward table, on the customer, added by the scheduled pass the first time it runs, if no such index is there already. Core ships the table without one. Nothing ever removes it.
Event rows on the order history, the checkout, customer creation and deletion, the storefront account pages, OpenCart's Remove Reward button and the admin's Customers menu, all under the code loyalty.
One hourly scheduled task, under Extensions → Cron Jobs. It repairs failed writes, pays birthday bonuses and runs expiry. It only does anything when something on your host calls OpenCart's cron.php, or the command below. Its own route answers a browser Not found; cron.php itself can be requested by anyone, which only runs the pass when it is due (see limits).
The storefront's Reward Points page is replaced by Loyalty's own, at the same link in the customer's account menu, while the programme is on. With it off, core's page is served as if Loyalty were not installed.

OpenCart 4.1.0.4: run the scheduled task yourself¶

On 4.1.0.4 OpenCart's own cron.php stops before it reaches any extension (see requirements), so on that release expiry, the expiry warning, the birthday bonus and the repair of failed writes do not run through OpenCart's scheduler. The Loyalty screen says so on such a store. Earning, spending and reversal are unaffected, because they happen when an order changes status rather than on a schedule.

Run the same task from a crontab line of your own instead:

10 * * * * cd /path/to/store && php extension/loyalty/loyalty.php

It takes no arguments, exits 0 once the task has run and 1 when it could not start, and writes what it did to Loyalty's log, like the scheduled run. Any other release can use it too, if you would rather schedule it yourself. Until something runs it, nothing is lost and nothing expires.

Refused installs¶

Below OpenCart 4.0.2.0, installing writes nothing at all: no tables, no events, no settings. The reason is in the log.
Below PHP 8.1, the same.
A user group that may not modify extensions is refused the install and the uninstall, and the log says so.

The log is the shared diagnostic file described on what Kyvero extensions log.

Updating¶

OpenCart updates an extension by uninstalling it and installing the new version. The installer refuses to remove the files while either half is still installed, so uninstall the order total first, then the module, then upload and install the new version in the order above. Every setting on both screens comes back as you left it, for every store, including whether the programme is on and when earning started. Nothing a customer has earned is touched: uninstalling removes this extension's event rows and scheduled task, and nothing else. What an update asks for again is listed in the changelog.

Uninstalling¶

Taking both halves off removes the event rows and the scheduled task, and nothing else. Your customers' points stay in OpenCart's reward table and remain their balances, and Loyalty's history of them stays in its own tables.

Uninstalling does not switch OpenCart's own Reward Points total back on, so until you do, your customers have points and no way to spend them.