Rewards and gift cards

Rewards and gift cards

Reward types

wp_oloyalty_rewards.type supports nine reward kinds:

• cart_pct - percentage off the cart
• cart_fixed - fixed amount off the cart
• product_pct - percentage off a specific product
• product_fixed - fixed amount off a specific product
• free_product - free product line item
• free_ship - free shipping
• gift_card - issue a gift card on redemption
• store_credit - add to the member's store credit balance
• custom - extension point

A reward's cost can be a flat points_cost or a sliding cost_rule (for example 100 points per $1 of value). Conditions in the conditions JSON gate the reward by tier, by minimum cart total, or by date window.

Redemption lifecycle

Redeeming a reward writes to wp_oloyalty_redemptions with status pending, then transitions through applied (added to a cart or order) and consumed (order completed) or reversed (refunded). Each redemption carries a unique code so it can be tracked on the corresponding WC order.

Gift cards

Gift cards are a first-class object in wp_oloyalty_giftcards. They are closed-loop instruments and not in PCI scope.

Issue via OLoyalty_GiftCards::issue($args):

• amount - decimal value, currency tracked separately
• currency - defaults to the store currency
• issued_to_email - recipient (optional)
• delivery_at - schedule for future delivery; status starts as pending
• expires_at - jurisdiction-aware expiry
• note - free-text note included on delivery
• code - explicit override, else generate_code() produces a cryptographically random code

Every issue, redeem, refund, adjust, or void writes a row to wp_oloyalty_giftcard_transactions with balance_after, so the audit trail is complete.

AML threshold

For large issuances, set giftcards.aml_threshold. Cards at or above that amount are issued with status='pending' and an audit log entry tagged giftcard.aml_review, so a human reviews before delivery.

Partial redemption

Gift cards support partial redemption. Each redemption writes a redeem transaction and updates the card's balance. The card stays active until the balance hits zero or until expires_at is reached.

Bulk issue

OLoyalty_GiftCards::bulk_issue([$row1, $row2, ...]) iterates one issuance at a time, returning the array of created cards. Useful for B2B gifting or holiday batches.