Skip to content

Reward rules

Gamification 0.9.97 / Automation

Reward rules

Convert canonical events into deterministic Pro reward actions.

Reward amounts in the administrator editor use the selected point type's configured precision. Storage and ledger calculations retain exact fixed-point values; the editor does not expose meaningless trailing zeroes.

Reward rules are where administrators configure automatic rewards. A rule chooses what a member does, who receives the result, what is awarded, and any limits or reversal behavior. Internally, Pro rules listen for provider-neutral event keys and can award or deduct points, grant an achievement, or assign a rank. Those technical keys stay behind the guided editor unless an administrator opens the custom-integration controls.

Conditions, recipient resolution, daily/lifetime/global limits, and cooldowns are evaluated against a versioned rule. Limit decisions and their resulting action are serialized per rule, so simultaneous events cannot overrun an award cap. Event/rule/version identities prevent duplicate actions.

Each Reward rule can contain up to ten ordered outcomes. The engine attempts them from top to bottom and gives every outcome its own event/rule/version/action idempotency identity and immutable result row. Existing single-action rules are read as one outcome without a migration step. A completely successful run remains awarded; if one outcome succeeds and another fails, the aggregate run is partial, the successful movement is retained, and the failed outcome is explained separately. Partial runs consume the Reward rule's configured limits so a later event cannot bypass a cap after receiving only part of the configured reward.

Point awards and deductions can optionally define a linked reversal policy. The guided choices cover trash or permanent deletion of the same WordPress content/comment; advanced integrations can provide another dotted reversal event key. A reversal matches the canonical provider, subject type, and subject ID recorded by the original outcome. It then reverses that exact transaction through a compensating ledger transaction, records an immutable reversal decision, and cannot reverse it twice. It never guesses an amount from the current Reward rule definition. Achievement and Rank outcomes do not offer this ledger-only policy. Use their owning domain workflow when revocation semantics are required.

Open Reward rules and choose Edit to revise an existing definition. The editor restores every saved field and requires a short change note. Saving does not overwrite the version used by earlier runs: it archives the complete current definition, creates the next numbered version, and rejects the save if another administrator changed the Reward rule after the page was opened. The read-only history below the editor shows when each replaced version was saved and why. Pausing or publishing from the index changes only operational state; editing configuration creates a new definition version.

For a native WordPress rule, choose a member activity and a confirmed member-content type. Ordinary posts are available by default; an integration must explicitly declare any additional front-end submission type, so products, orders, templates, pages, and other publicly queryable administrative records are never guessed to be member activity. The everyday list excludes WordPress application records, taxonomy-term administration, destructive lifecycle events, and raw status transitions. Registration, member content, comments, and uploads remain directly available. Installed addons can contribute their own plain-language activities without exposing provider tables or hook names. The full adapter contract is not removed: custom integrations and migrated definitions can use the collapsed Custom integration activity control. The event key is a stable internal routing identifier that prevents an addon rename or UI-label change from breaking a rule; most administrators never need to see or edit it. Guided selections are also resolved and validated on the server, so normal WordPress form submission works without JavaScript.

Points outcomes may have ordered member-based amount adjustments. The first row matching one of the recipient's current ranks or earned achievements can increase or reduce the base amount by an integer percentage, add or subtract an exact amount, or replace it with an exact amount. The same adjustment applies consistently to every points outcome in the rule. Rank assignments and earned achievements are each loaded at most once per member during a request, calculations use decimal-string arithmetic, and ledger metadata keeps the base amount, final amount, matched definition, operation, and configured value.

Publishing a native WordPress reward rule automatically enables the primary and linked-reversal listeners it requires. If Integration settings use selected content types or taxonomies, the chosen scope is added without removing other administrator selections. Published reward rules, achievement requirements, quest steps, and streaks keep their required capture enabled. Pause or replace the dependent definition before removing that listener or scope. Enabling capture records future facts only and never invents historical activity.

Provider migration never publishes a Reward rule. GamiPress requirement and myCred hook reviews can create a draft only when the trigger, recipient, conditions, amount, audience, lifecycle, and supported limits translate exactly. Every source is re-read immediately before conversion. A changed source returns to review, and a source edited after conversion is shown as a conflict without altering the draft. Review the draft in Reward rules, decide which engine will own the reward, disable the equivalent provider rule or hook when appropriate, and only then publish Cointacted.

Use the Diagnostics event simulator to preview matching rules, every ordered outcome, linked compensating transactions, and progress without storing an event or changing a balance. Rule-run diagnostics distinguish partial runs and show the number of outcome and reversal audit records. Paid listeners are not registered while Pro is inactive.

Was this documentation helpful?Your response helps us improve this page.