Configure and verify referral rewards

GymCore stores referral rewards as versioned, mode-specific configurations. A new or migrated configuration remains off until an owner enables it and all delivery-readiness checks pass. New referral attributions snapshot the effective revision; later edits do not change existing decisions.

Access and dependencies

• Open GymCore Admin > GymCore Settings > Referrals with gymcore_manage_settings; WordPress administrators with manage_options also qualify. manage_woocommerce alone does not grant access.
• WooCommerce and Action Scheduler must be available before any reward mode can be enabled.
• WooCommerce fixed-cart coupon snapshots the current WooCommerce store currency on every save. A later enable save creates another revision using the currency current at that save; GymCore does not present a separate changed-currency review gate.
• Integer outbound-message credits require an external PHP integration that registers the version 1 credit ledger, a credit-aware sender, and ready Twilio transport. Core provides no ready registration. Credits are message units, not money, Twilio balance, or carrier segments.
• Registered receipt-based custom handler requires an external PHP integration that registers a matching contract version, idempotency, reconciliation, readiness, and durable delivery callbacks. Core provides no handler registration. Activation trusts the descriptor’s declared readiness; the delivery worker rejects missing callbacks later.
• Referral records connect two customers and purchase activity. Restrict access and never disclose one person’s order details to another.

Use fictional people and a non-production site until the complete reward path has passed.

Save a disabled revision first

1. Open GymCore Admin > GymCore Settings > Referrals.
2. Clear Program enabled.
3. Choose Reward mode.
4. Enter only the selected mode’s values:
   • Coupon amount: a positive store-currency decimal no greater than 100000.
   • Message-credit units: a whole number from 1 through 10000.
   • Custom: a registered reward identifier, owner description, handler key, and matching handler contract version.
5. Add an optional Configuration note without member data or secrets.
6. Select Save changes, reload the page, and confirm the preview and values.

Expected: GymCore stores a new disabled revision. A stale browser tab, invalid field, unregistered custom handler, or mismatched handler version rejects the save without replacing the current revision.

Enable only after readiness passes

1. Confirm the selected mode’s dependencies are installed, configured, and tested.
2. Select Program enabled.
3. Select Save changes.

Expected: Saving with Program enabled creates a new enabled revision only when the save-time readiness result is ready; it does not activate the earlier disabled revision. If that check fails, GymCore preserves the prior revision and reports that the reward program remains unchanged.

Readiness is checked during the enabled save, not continuously when a referral is attributed. Recheck dependencies after any provider, currency, scheduler, ledger, sender, or handler change. Clearing Program enabled creates a disabled copy of the current revision without revalidating a degraded mode dependency; save and reload to confirm it is off.

Enabling affects only referral attributions created while that revision is effective. It does not add a promise or backfill a decision for older referrals.

Test attribution, qualification, and delivery

1. Submit a fictional referral through the exact installed capture path.
2. Confirm the referral record identifies the intended fictional referrer and referred customer.
3. Confirm the decision records the expected configuration revision and selected mode.
4. For a non-subscription fixture, complete the first eligible paid order. Do not treat a subscription renewal as qualification evidence yet: current source compares the subscription’s total payment count with 1, while WooCommerce Subscriptions normally includes the paid parent order in that count. The first-renewal path remains blocked until renewal-only behavior has an installed WCS regression.
5. Allow the scheduled worker to run, then inspect the decision, attempt, and source-system evidence.

Expected for a supported fixture: One immutable decision progresses from pending to qualified and then to succeeded. Delivery evidence is mode-specific:

• Coupon: one opaque, non-stackable fixed-cart coupon, one use, no sale items, and 183-day expiry. Delivery rejects a missing or invalid recipient; verify the coupon has the fictional referrer’s non-empty referrer email restriction and passes exact coupon policy readback. initial_order_only is recorded as coupon metadata, so verify that the installed checkout/subscription stack actually enforces it before customer use.
• Message credits: one unique committed positive ledger entry for the promised integer units.
• Custom: one durable handler receipt or authorized manual-fulfilment record. A hook firing or request acknowledgement is not delivery proof.

Do not manually replay a failed or unknown delivery. GymCore reconciles bounded batches every five minutes and terminalizes delivery as exhausted after five delivery attempts. An unknown coupon reconciliation can remain issuing; escalate immediately with safe decision/attempt identifiers instead of retrying it.

Reverse or recover

Clear Program enabled, save, reload, and confirm the active revision is off to stop new reward decisions. This disable path preserves the current mode values and does not require a missing or changed custom handler. Existing decisions and delivered rewards remain unchanged. Correct or void an issued benefit in its owning source system, preserve an audit note, and follow the approved customer-impact policy.

Verify in the source systems

Confirm the active revision under GymCore Settings > Referrals, the relationship and decision in GymCore referrals, the qualifying order in WooCommerce or the subscription provider, the scheduled action result, and the issued benefit in WooCommerce coupons, the message-credit ledger, or the custom handler’s durable records. This guide is verified against Gym Core 2.2.0.