Recommendation Management

Overview

/admin/referrals shows each individual referral advertisement in the system. Two tabs:

• Overview — Stats-Cards (Total / Redeemed / Qualified / Rewarded / Voided), filter by status, paginated table.
• Configuration — all program settings (see article „Program Configuration").

Stats-Cards

The cards show total numbers across all tenants. The conversion- funnel results from the difference:

• Redeemed → Qualified = how many advertisements reached the condition.
• Qualified → Rewarded = how many Stripe-calls ran successfully.

Filter

Status filter in the dropdown:

• Redeemed — the code was just used, advertisement is waiting for qualification.
• Review — Anti-Fraud marked it for manual inspection.
• Qualified — condition fulfilled, next cron-tick pays out.
• Rewarded — Stripe-Grant successful.
• Expired — window lapsed without qualification.
• Voided — Manually voided by the admin or reversed by Clawback.

Detail Page

Click on a row → /admin/referrals/:id:

• Master Data: Code, Referrer + Referred Tenant (linked to the Tenant Detail Page), Reward-Snapshot.
• Stripe IDs: stripe_credit_id and/or stripe_coupon_id — direct access to the Stripe Audit-Trail.
• Timeline: chronological audit events for the advertisement (referral.redeemed / referral.qualified / referral.rewarded / referral.grant_failed / referral.voided etc.).
• Notes: accumulated notes (Grant-Failure-Reasons, manual Admin-Notes).

Manual Actions

Three buttons on the detail page:

• Force Qualification — available only for status „Redeemed" or „Review". Sets status to Qualified, snapshots the current Reward configuration. The next Grant-Cron pays out.
• Manually Payout Reward — available only for status „Qualified". Triggers the Stripe-Grant immediately with the same referral_grant_<id>-Idempotency-Key as the cron — a second click does not create a duplicate credit.
• Void — sets status to Voided with reason. Already granted Stripe-Credits are not automatically clawed back — the Clawback-path (customer.subscription.deleted-webhook) is responsible for that.

Each manual action writes a referral.admin_override-audit-entry with admin_override=true flag, so it is distinguishable later what was automatically and what was manually created.

Stripe Audit-Trail

A click on a Stripe-ID copies it to the clipboard; the Stripe-Dashboard-URL is e.g. https://dashboard.stripe.com/customers/<cust_id>/balance_transactions/<tx_id>. In the Stripe-Dashboard you also see correction bookings (Clawback- Reversals).