OLoyalty v1.0.0-alpha

What OLoyalty does

OLoyalty sits on top of WooCommerce. It tracks every point earned and spent in an append-only ledger, qualifies members into tiers based on configurable rules, ships a catalog of redeemable rewards (cart discounts, product unlocks, gift cards, store credit, custom payloads), runs a referral program with fraud scoring, and dispatches every change as a typed event for the rest of your stack to react to.

Getting installed

First program in 5 minutes

From fresh activation to a live loyalty program with one earn rule, one tier upgrade, and one redeemable reward.

Plugin architecture

13 database tables

All prefixed with {prefix}oloyalty_. Created on activation through dbDelta. Hot queries are indexed: member-by-user_id, ledger-by-(member_id, created_at desc), giftcard-by-code, referral-by-referrer.

Admin interface

Top-level menu OLoyalty (slug oloyalty) with capability-scoped submenus. Built with the same admin chrome as the rest of the Orravo suite for first-party feel.

Settings reference

All settings stored in wp_options under key oloyalty_settings as a single nested array. Access via OLoyalty_Settings::get('group.key').

Points engine

Earn rules describe how members accumulate points. The ledger is append-only: every change writes a row with the new balance_after, so balances are auditable end to end. Adjustments, expirations, and reversals are first-class types alongside earn / redeem.

Member tiers

Tiers are ordered by rank. Qualification rules are a JSON document evaluated against the member's lifetime stats. Perks JSON is read by the points engine, rewards engine, and any custom code that calls OLoyalty_Tiers::perks_for($member).

Rewards catalog

A reward is a row in oloyalty_rewards with a typed payout and an optional points cost. Redemption issues a single-use code (UNIQUE) that maps cleanly onto a WooCommerce coupon, gift card, store credit issuance, or any custom payload your site cares about.

Gift cards

Gift cards have a UNIQUE code, fixed initial amount, and configurable expiry. Issuance writes a row in oloyalty_giftcards plus an issue transaction. Each redemption appends a redeem transaction with the new balance, so the audit trail is complete.

Store credit

Store credit lives on the member record (UNIQUE per member + currency). It auto-applies at checkout and never has a code, so it can never leak. Every change writes a row in oloyalty_credit_transactions with the new balance.

Referral program

On enrollment each member gets a UNIQUE referral_code. Friends apply the code at checkout (or land via ?ref=CODE). The conversion handler runs fraud scoring first, and a score at or above referrals.fraud_threshold (default 0.7) routes the referral to manual review.

WooCommerce integration

OLoyalty hooks WooCommerce's order lifecycle directly. Points are awarded on woocommerce_order_status_completed and woocommerce_order_status_processing; reversed on refund or cancellation; and the review-points rule listens for comment_post on product comments.

Shortcodes & blocks

Three shortcodes plus three matching Gutenberg blocks. All render the current member's data with no configuration required.

[oloyalty_balance]
[oloyalty_balance show_tier="false" show_progress="true"]

[oloyalty_rewards]
[oloyalty_rewards type="cart_fixed,gift_card" affordable_only="true"]

[oloyalty_referral]
[oloyalty_referral show_code="true" share_buttons="email,whatsapp,x"]

Suite integrations

First-party bridges to other Orravo plugins. Each is togglable in Settings → Integrations and runs zero-config when both plugins are active.

REST API

Namespace oloyalty/v1. Auth via standard WordPress nonces (admin-side) or application passwords (server-to-server). All routes return JSON. The /openapi endpoint serves a live OpenAPI 3.0 spec for codegen.

Developer hooks

OLoyalty ships a typed event bus (OLoyalty_Events::dispatch) that mirrors every emission through do_action. You can subscribe to any event with vanilla add_action.

Helper functions

Procedural helpers for the common stuff. Wraps the underlying classes so themes and snippets stay readable.

WP-CLI

Eight wp oloyalty commands cover member, points, tiers, giftcard, credit, referral, report, and reward operations. Wire them into your deploy pipeline or cron jobs.

$ wp oloyalty member list --tier=gold --format=table
→ 6 gold-tier members listed

$ wp oloyalty points adjust 42 +500 --reason="customer service credit"
→ ledger #4912 written · balance 4,820 → 5,320 · ok

$ wp oloyalty tiers recalc
→ recalculated 30 members · 2 promotions · 0 demotions · 14 unchanged

$ wp oloyalty giftcard issue --to=adaeze@velluma.com --amount=25
→ issued GC-3F8A1C90 · $25.00 · expires 2027-05-07 · email queued

$ wp oloyalty credit issue --member=42 --amount=10
→ credit_transactions #318 · balance 0.00 → 10.00

$ wp oloyalty referral approve 14
→ referral #14 approved · referrer +500 · friend +250

$ wp oloyalty report liability
→ 30 members · 142,840 pts outstanding · $1,428.40 liability @ $0.01/pt

$ wp oloyalty reward list --status=active
→ 10 active rewards · 22,400 pts spent (30d window)

Admin capabilities

Six area capabilities so loyalty operations can be split across roles. Granted to the administrator role on activation; reassign to your own roles via standard add_cap.

Liability reporting

Outstanding loyalty points are a real liability on your books. The liability snapshot computes total outstanding points, multiplies by your configured value_per_point, and stores the result with a timestamp so you can chart it over time.

GET /wp-json/oloyalty/v1/reports/liability

{
  "snapshot_at": "2026-05-07T14:42:00Z",
  "members_with_balance": 22,
  "points_outstanding": 142840,
  "value_per_point": 0.01,
  "currency": "USD",
  "estimated_liability": 1428.40,
  "by_tier": {
    "bronze":   { "members": 12, "points":  4820,  "estimated":   48.20 },
    "silver":   { "members":  8, "points": 14620,  "estimated":  146.20 },
    "gold":     { "members":  4, "points": 38400,  "estimated":  384.00 },
    "platinum": { "members":  2, "points": 85000,  "estimated":  850.00 }
  }
}

vs. the loyalty landscape

One purchase. Lifetime updates.

No tiers based on member count. No per-redemption tax. Pay once, install on the sites in your tier, get every future update free, including the v1.0 stable release.

What's shipped