Wren Loyalty documentation

Install

Wren Loyalty needs WordPress 6.6 or newer, WooCommerce 9.0 or newer, and PHP 7.4 or newer.

In WordPress, go to Plugins → Add New → Upload Plugin and upload wren-loyalty.zip, or search for "Wren Loyalty" once it is listed on WordPress.org.
Activate it. A notice on the Plugins screen links to the setup.
Open WooCommerce → Loyalty and follow the three short steps. Nothing changes for customers until you click Launch my program.

To install Pro, upload wren-loyalty-pro.zip the same way. Pro needs the free plugin active.

How customers earn

Customers earn points for every currency unit they spend. With the default of 1 point per $1, a $58 order earns 58 points.

What counts: product totals after discounts. Shipping, taxes and fees are off by default; turn them on under Settings → Earning.
When points arrive: when the order is Completed (default) or Processing. Until then the customer sees them as pending.
Rounding: down (default), nearest, or up.
Per product: on the product's General tab, set Loyalty points to a fixed number per item, or "Earns no points". Variations inherit the parent's setting.
Per category: the same options on the product category screen. Product settings take priority.
Welcome bonus: given once when an account is created.
Review bonus: given when a review is approved, once per product. By default only verified buyers qualify.

The points an order earns are calculated when it is placed and stored on the order, so changing your rates later never rewrites history.

How customers redeem

Logged-in customers see a points panel in the cart and checkout. They choose how many points to use with a slider or by typing a number, then click Apply. The discount appears as a cart discount labelled "Points".

Rate: how many points equal one currency unit off. The default, 100 points = $1, gives 1% back at the default earn rate.
Minimum points and minimum order subtotal before points can be used.
Maximum discount per order, as a percentage of the order or a fixed amount.
Sale items: optionally exclude them from the points discount.

Points are deducted when the order is placed. If the order is cancelled or fails, they are returned. If a customer's balance drops (for example they spend the points in another tab), checkout asks them to review the order instead of creating a negative balance.

Refunds and cancellations

Partial refund: removes points in proportion to the refunded amount. Refund half the order, lose half its points.
Full refund: removes all points the order earned, and returns points it used (you can turn the return off).
Cancelled or failed: removes earned points and returns used points.
Reopened orders: if a cancelled order is completed again, its points are awarded again.

Each change is a separate line in the customer's history, so you and the customer can always see why a balance changed.

Managing customers

WooCommerce → Loyalty → Customers lists everyone with points. Search finds any customer by name or email. Click a customer to see their balance, pending points and full history, and to add or remove points. A reason is required and appears in the customer's history.

The WordPress Users screen also shows each user's balance in its own column.

Importing from another plugin

Open WooCommerce → Loyalty → Import & tools while your old plugin's data is still in the database. Supported sources:

WooCommerce Points and Rewards (official extension)
YITH WooCommerce Points and Rewards
WPLoyalty (customers are matched by email)
Points and Rewards for WooCommerce by WP Swings, including older MakeWebBetter installs
MyRewards (WooRewards)
Simple Points and Rewards
myCred (default point type; decimals are rounded)

Click Preview to see how many customers and points will be imported, then Import now. Each customer's balance is imported once, so running it again is safe. The old plugin's data is never changed. When you're done, deactivate the old plugin so customers don't see two programs.

Balance check and export

Every balance is a sum of ledger entries. Check balances compares each customer's stored balance with their ledger and offers to rebuild any that differ. Download ledger CSV exports every transaction.

WP-CLI

wp wren balance <user>
wp wren adjust <user> <points> --reason="Sorry for the delay"
wp wren sync-orders <order_id>
wp wren sync-orders --all
wp wren doctor [--fix]
wp wren import [<source>] [--dry-run]

<user> accepts an ID, login or email. sync-orders --all is safe to run repeatedly.

For developers

Shortcodes: [wren_points_balance] and [wren_ways_to_earn]. Templates in templates/ can be overridden. Useful filters:

wren_loyalty_order_points ($points, $order)
wren_loyalty_earn_multiplier ($multiplier, $user_id, $context)
wren_loyalty_award_statuses ($statuses)
wren_loyalty_product_redeemable ($bool, $product)
wren_loyalty_ways_to_earn ($ways)

Action wren_loyalty_points_recorded fires after every ledger entry with the entry as an array.

Troubleshooting

The points panel doesn't appear in checkout

The customer must be logged in and have points, or the order must earn points. Check that the program is active under Settings and that redeeming is on.

A balance looks wrong

Open the customer's history to see each change. Run Check balances under Import & tools, or wp wren doctor.

Still stuck?

Email hello@wrenplugins.com. We reply within one business day.

Documentation