Admin & Operations Manual

For Ribbit.Deals admins · Companions: Functional Spec · System Architecture · ✅ Accounts checklist

This manual explains how to run Ribbit.Deals day to day: approving businesses, helping members and owners, managing fees and categories, publishing agreements, and keeping billing on track. It describes the system as it works today and is updated whenever an admin screen changes. Each update gets a new version number and a line in the revision history at the end.

• 1. Getting in
• 2. Routine checklists
• 3. Overview: reading the numbers
• 4. Businesses
• 5. Deals
• 6. Members
• 7. Fee settings
• 8. Categories
• 9. Agreements
• 10. Statements & billing
• 10a. Rewards & referrals
• 11. Ribbit cards
• 12. Helping owners and members
• 13. Security & the audit trail13a. Backups & restore drill
• 14. Where everything lives
• 15. Glossary

1. Getting in

The admin is at beta.genxapp.org/admin. Sign in with your own email and password. Admin access belongs to your personal account, so each admin signs in as themselves and every action is recorded under their name.

• Forgot your password? Use Forgot password? on the sign-in page. The emailed link works once, for 60 minutes. Setting a new password signs your other devices out.
• “This page is for admins.” You’re signed in on that browser with a different account, often a business owner account you were testing with. Click Sign in as an admin; you’ll come straight back to the page you wanted. To avoid switching back and forth, use a private window for the second account.
• The old admin address (ribbit.genxapp.org/admin.php) now forwards to the new admin.

Screens with several parts (Rewards, Agreements, Fee settings, Statements, and each business’s and member’s page) show them as sub-tabs under the page title; click one (or use the arrow keys) to switch.

Your name is in the top right corner: click it for the account menu (your email, this manual, and Sign out). On a phone or narrow window, the tabs fold into the ☰ menu at the top left. Long tables show 25 rows a page; use Previous and Next below the table (sorting and Export CSV always cover every row).

The tabs across the top are Overview Businesses Deals Members Fee settings Categories Agreements Rewards Statements. Most tables can be sorted by clicking a column heading and downloaded with Export CSV.

2. Routine checklists

Every day (5 minutes)

• Businesses → awaiting approval. Verify and activate new businesses (section 4) so their deals can go live.
• Overview. Glance at verified redemptions and the void rate. A sudden jump in voids is worth a call to that business.
• If daily billing is on: check Statements for any daily charge marked failed (section 10).

Every week

• Deals: look for deals marked NO REDEMPTIONS IN 14 DAYS or LOW CONVERSION, and use the coaching notes on the business’s page to guide a call.
• Members: check the Possible duplicate accounts card and merge any real duplicates (section 6).
• Businesses → applications in progress: businesses that started enrolling but stopped. A friendly call often finishes the sale.

Every month (on or after the 3rd)

• Statements are created and charged automatically at 6:00 AM Mountain on the 3rd. Open Statements, choose last month, and make sure every active business has a statement and none are marked failed.
• Check the Held for pricing card, if it appears (section 10).

3. Overview: reading the numbers

The Overview answers one question: is Ribbit.Deals paying off, and which way is it heading? Every card opens the detail behind it when clicked; cards with a small line show the trend over the period. Switch between Last 7 days and Last 30 days, and use 🖨 Print for a clean printed or PDF copy (it notes when it was printed).

Revenue

Earned this month so far (performance fees, operations for the days elapsed, and activations), with what the month is on pace for; performance fees for the period; the monthly operations total; and how this month’s projection compares with all of last month. The Revenue by month chart shows the last six months, split into operations, performance fees and activations.

Business performance

The share of active businesses that had redemptions in the last 30 days, average redemptions per business, how many need attention (no live deal, or no redemptions in 14 days), and active businesses with their live deals and locations.

Growth & early signals

These move before revenue does: verified redemptions, deals opened (and how many were redeemed), new members, members who joined by invite, enrollment applications in progress, active members, the void rate (a sudden rise is worth a call to that business) and estimated member savings.

4. Businesses

The Businesses tab lists businesses still enrolling, businesses awaiting approval, and active businesses with their recent activity. Labels flag what needs attention: TOP PERFORMER, NO LIVE DEALS, NO REDEMPTIONS IN 14 DAYS, and HIGH VOIDS. Click a business to open its page.

Activating a new business

After a business signs its agreement and pays the activation fee, it waits for you. Its page shows an Agreement card with what it signed, whether the activation fee was paid, and which agreement version it accepted.

1. Confirm the business is real and reachable: call the contact number, and check the address and website.
2. Confirm the activation fee shows as paid. If it doesn’t, you’ll get a warning before activating; only continue if payment was arranged another way.
3. Click Activate business. Its deals can now reach members, and its billing period starts today.

Deal coaching

Each deal on a business’s page shows how often it was shown, opened, redeemed, and voided in the last 30 days, with a daily chart and plain-language coaching notes. Every note shows its evidence: the deal’s own numbers and the benchmark it’s judged against, for example “Opened by 6% of members who saw it (3 of 48). Deals that catch attention are opened by 10% or more.” Use them to guide calls with owners. The page also lists every statement and charge the business has had.

Changing a business’s performance fee

The Performance fee card shows the fee in effect and where it comes from (the rate they signed, their category, or an override). To set a special rate for one business, choose Flat $ or Percent %, enter the amount and a reason, and click Save. It applies to new redemptions from that moment. Choose No override and save to return them to their signed rate.

5. Deals

The Deals tab lists every live and paused deal across all businesses, with redemptions, views and labels: TOP PERFORMER, NO REDEMPTIONS IN 14 DAYS, NEAR CAP (close to its redemption limit), and LOW CONVERSION (opened often, rarely redeemed). Owners create and edit their own deals in their business tools; admins review and coach.

6. Members

Search by name, email or phone, then click a member to open their page.

• Profile: correct a name, email or phone and click Save profile.
• Password help: nobody can see a password, admins included. Email reset link sends a link for the member app; Reset link (business sign-in) sends one for business owners. Each works once, for 60 minutes.
• Suspend: Suspend account needs a reason, which is kept in the log. A suspended person can’t sign in or redeem. Admins can’t be suspended until their admin access is removed, and you can’t suspend yourself.
• Admin access: Grant admin access or Remove admin access. You can’t remove your own access, and there must always be at least one admin.

Adjusting points

In Adjust points, enter a number (use a minus sign to take points away) and a reason, then click Adjust points. This adds an entry to the member’s points history; nothing is erased. The member sees the reason, so write it for them. A balance can’t go below zero.

Merging duplicate accounts

The Members tab lists accounts sharing a phone number, and each member’s page lists likely duplicates (same name or phone) under Duplicate accounts.

1. Click Review merge next to the duplicate (or enter the other account’s email and click Review merge).
2. Check the panel. By default the older account is kept (its invite code may already be shared) and the person signs in with the email they used most recently. Use ⇄ Swap or the sign-in choice to change either.
3. Read “What happens”: points are combined, and redemptions, badges, business links, admin access and invites move to the kept account.
4. Click Merge accounts and confirm.

7. Fee settings

The Fee settings tab holds the rates new businesses agree to. Changes apply to new agreements only; enrolled businesses keep the rates they signed unless you override one business (section 4).

• Activation fee: one-time, paid at enrollment.
• Operations fee and Charge the operations fee: monthly, per business or per location.
• Default performance fee (flat): per verified redemption, for any category without its own fee (section 8).
• Annual discount: optional discount for paying operations a year at a time. Leave it blank and businesses only see monthly.
• When performance fees are charged: on the monthly statement, or daily at the end of each day. With daily, set a Minimum daily charge so businesses aren’t hit with many tiny card charges (each costs about 30¢ plus 2.9% in card fees).

Click Save fee settings. Every change is kept in the Change history below: who, when, from what, to what.

Enter to Win drawings

In Rewards → Enter to Win. Click + New drawing: name the prize, add a short description and an icon, choose when entries open and close (whole days, Utah time), and paste the official rules (or link to them). It stays a draft (members still see “coming soon”) until you open it, tick “The founders and counsel have approved these official rules…” and click Go live; your confirmation is recorded. Only one drawing can be live at a time, and once live its prize, dates and rules can’t change. Members enter once each, free; entry never requires a purchase or redemption. After entries close, click Draw winner: one eligible entry is chosen at random (Ribbit.Deals admins and suspended accounts can’t win), the winner is notified in the app, and you see their name and email to arrange the prize. Every step is recorded.

Location rules

Also on the Fee settings tab. Location Lock (members must be at the business to redeem) should stay Active: it’s what makes every billed redemption a real visit. Switch it to Disabled only for a demo away from the business, and back to Active right after; while it’s disabled, the Overview shows a red warning. Choose how close counts as “at the business”: In the building (about 165 ft, strictest: phone GPS indoors can be off by 100 ft or more, so some real customers may be told they’re too far), In the parking lot (about 500 ft), In the vicinity (about 1,300 ft, recommended), or Custom. The new-deal alert range sets how far away members can be and still get push alerts about a business’s new deals. Every change is kept in the history below the card.

8. Categories

Categories are what members browse by. Members see changes right away.

• Click a category’s name (or its ▸ button) to show its sub-categories, or use Expand all and Collapse all. Type in Find a category to filter.
• Drag a category by its ⠿ handle to set the order members see (mouse or finger), or use ↑ ↓.
• Edit opens a panel on the right (full screen on a phone); it closes when you save, cancel, click outside it or switch tabs. It changes the name, icon (type an emoji or pick one), which category it sits inside, visibility to members, and its performance fee (Inherit, Flat $ or Percent %).
• + New category adds a main category; + Add sub-category adds one inside it. Sub-categories go only one level deep.
• Average purchase and typical item price (in the editor) drive members’ estimated savings: percent-off deals use the average purchase, free-item and buy-one-get-one deals the typical item price. Leave a sub-category blank to use its main category’s figures. Setting them fills in estimates for earlier redemptions that had none; after that, each redemption’s estimate stays as recorded.
• Hide rather than delete. A category used by any business, or with sub-categories, can’t be deleted. Untick Visible to members instead.

9. Agreements

The Agreements tab manages the Business Participation Agreement. Published versions are never edited. To change the agreement, publish a new version; there is always an exact copy of what each business accepted.

1. Edit the text in Publish a new version (it starts from the current text). Lines starting with “## ” become headings; a blank line starts a new paragraph.
2. Decide who it applies to. Leave the box unticked to apply it to new enrollments only. Tick “Existing businesses must accept this version too” to ask every enrolled business to accept it; they’ll see a reminder in their business tools.
3. Click Publish as v… and confirm.

The tab also shows the version history, the Acceptance ledger (who accepted which version, when, and how they signed), and the businesses not yet on the current version.

10. Statements & billing

The promise to businesses: they only pay when it works. A redemption is billed only after its 48-hour void window has closed, only if it wasn’t voided, and never twice.

What runs automatically

• Monthly statements: on the 3rd at 6:00 AM Mountain, for the month before. Each covers that month’s operations fee (the first month is prorated to the day the business went live; annual plans are billed once a year) and the performance fees not yet billed. The card saved at enrollment is then charged.
• Daily charges (only if Fee settings say daily): every night at 11:00 PM Mountain, redemptions past their void window are charged once they reach the minimum daily charge. The monthly statement still bills operations and anything left over.

The Statements screen

• Choose a month and it loads, opening on Needs attention (statements still due or failed) with the month’s totals above: billed, collected, still due and failed charges. Use the buttons to see Paid, Nothing due or All, and the search box to find a business. The last 12 months lists every month’s totals and state; click one to open it.
• Each business’s admin page also lists every statement and charge it has had. Create missing statements fills in any business without one; it never bills anything twice.
• Charge or Retry charge charges one statement; Charge all unpaid charges every unpaid statement for the month.
• Mark paid records a payment made another way (for example a check); you’ll be asked how it was paid.
• Failed statements show the reason, for example a declined card or a card needing the business to confirm. Contact the business, then retry.
• Held for pricing: redemptions on a deal with a percentage fee but no typical purchase. They’re never guessed. Ask the business to add the typical purchase to that deal; the redemptions are billed on the next run.

Every statement (and the activation receipt) can be opened and printed, and businesses see the same statements in their business tools under Account.

10a. Rewards & referrals

Members earn points for each verified redemption. If a business voids the redemption, those points are taken back automatically.

Referrals: every member has an invite code and a share link on their Rewards screen. A referral counts when a friend joins with that invite and makes their first verified redemption. Then both earn points: the friend gets welcome points, and the member who invited them gets invite points. If that first redemption is voided, the referral points are taken back too.

The Rewards tab holds the settings, all changeable at any time:

• Points per verified redemption.
• Referral program on/off, points for the member who invited, and welcome points for the friend.
• Most invite rewards one member can earn per month (0 means no limit). This stops one person farming the program; the friend still gets their welcome points.

Click Save reward settings. Changes apply from the next redemption; points already earned never change. The tab also shows referral totals, top inviters, recent referrals, and the change history. Someone can’t refer themselves, and each friend can only be rewarded once.

Badges

Badges reward members for reaching goals, and each can add bonus points. They also serve as referral and loyalty milestones (for example, 5 invited friends who redeemed earns a bonus). Manage them in the Badges section of the Rewards tab:

• + New badge or Edit: give it a name, a description members see, and an icon (tap one from the catalog or type any emoji). Choose what earns it: verified redemptions, different businesses redeemed at, invited friends who redeemed, or different weeks with a redemption. Then set the goal and the bonus points. The line under the icons shows exactly what members will see.
• Use ↑ ↓ to set the order on members’ badge shelves.
• Untick Live to stop a badge being earned. A badge members have already earned can’t be deleted (it’s part of their history); switch it off instead.

Members earn a badge on the redemption that reaches its goal and see it celebrated; their shelf on My Rewards shows earned badges and progress toward the rest. Voided redemptions never count, and if a void drops a member below a badge’s goal, the badge and its bonus points are taken back.

11. Ribbit cards

Each location has a Ribbit card for the counter: a QR code members scan, and a typed code (like POND-H3JC) as a fallback. Owners print their own from their business tools. Admins can print any business’s cards from its page with Print Ribbit cards.

Lost or copied card? On the printable-card page, click Issue new card for that location. The QR and the typed code both change, and the old card stops working immediately. Print the new card and have the business replace the old one. (The admin bar never appears on the printout.)

12. Helping owners and members

Business owners

• Joining: new businesses enroll at beta.genxapp.org/enroll in five steps: Business, Locations, Pricing, Billing & agreement (with secure card payment), Confirmation. Progress saves at every step.
• Running their deals: owners use the business tools at beta.genxapp.org/tools: Today, Deals (with drafts and previews), Redeemed, Ribbit card, Account. They stay signed in on their phone.
• End dates and uses per customer: in the deal editor, owners can set an optional end date (the deal runs through the end of that day, and members see the date and a countdown) and how many times one customer may use the deal (1 unless they change it).
• New deals reach returning customers: the first time a deal goes live, members who’ve redeemed at that business get a notification. Pausing and resuming doesn’t send it again.
• Redeemed shows one month at a time (tap a month), with that month’s redeemed, voided and fees, and filters for Final, Voided and Can still be voided. Redemptions still inside the 48-hour window are marked “48 HRS” and flagged at the top. Account → Statements shows the latest three; “All statements” lists every one by year.
• Voiding: owners can void a redemption for 48 hours if no purchase happened. It isn’t billed, and the member’s points are taken back.
• Password: “Forgot password?” on the sign-in page, or send them Reset link (business sign-in).

Members

• Redeeming needs location turned on, and they must be within the redemption range of the business (about 1,300 feet); otherwise the app tells them how far away they are. It confirms they’re at the business. Then they tap Scan the Ribbit card, or type the code printed under the QR.
• One per person per deal, unless the business allows more (the deal page says “Use it up to 3 times”, for example). A voided redemption doesn’t count.
• My Savings can be filtered by time (this month, last 3 months, this year) and category, and searched by business, deal or category; the total for that view shows above the list.
• “$ Saved” is an estimate: dollars-off deals count exactly; other deals are estimated from the category’s typical prices. Tapping the amount explains this in the app.
• Why we ask for a phone number: only to keep it one account per person and so admins can validate members. Ribbit.Deals never texts members or shares their number; alerts come through the app’s bell and, if they turn them on, push alerts.
• Can’t tell what they typed? Every password box has an eye button to show the password.
• Points are earned on each verified redemption and shown in My Rewards.
• The secret King Ribbit (for staff in the know): press and hold the frog at the top of the app for three full seconds. The frog is crowned, takes a royal leap with a golden glow, and plays the royal RIBBIT. A normal tap is still the normal ribbit. It needs the phone off silent and the RIBBIT! sound switched on in Account.
• Installing the app: point people to the install page (ribbit.genxapp.org/install.html until launch). Phones get the right steps for their device; computers show a QR code to scan with the phone. The welcome screen now leads with Step 1 · Put it on your home screen, before Join; Home offers an Install bar and Account has “Install the app on this device”. Android (Chrome, Samsung Internet, Edge) gets a real one-tap install. iPhones get steps for the browser they’re in: Safari, Chrome or Edge all work (Share → Add to Home Screen → Add), so nobody needs Safari. If the link opened inside another app (a QR scanner, Instagram, Gmail), the app says so and offers Open in Safari / Chrome or Copy link. The installed app on iPhone starts fresh, so the member’s invite code is shown and copied for them to enter when they join.
• Notifications (the 🔔 bell): members are notified when a friend joins with their invite, when that friend’s first RIBBIT earns them points, when they earn a badge, when a business voids one of their redemptions, and when a business they’ve redeemed at posts a new deal (once per deal, the first time it goes live). Tapping a notification opens the right place in the app.
• Alerts on the phone (push): members turn them on in Account → Alerts on this phone, or when offered after a RIBBIT. On iPhone they must install the app first (Apple only allows alerts there). If a member says alerts are blocked, they need to allow notifications for Ribbit.Deals in their phone’s settings. “New deals near me” uses their approximate location from when they last opened the app, and only alerts them about businesses within the new-deal alert range.
• Invites: My Rewards has their invite code a ready-made message they can edit, and Share / Copy message buttons (the app never sees their contacts). An invite card also rotates through the Home window. A friend who opens the link has the code filled in at sign-up. Both earn points after the friend’s first RIBBIT.
• Password: “Forgot password?” in the app, or send them Email reset link.

13. Security & the audit trail

• Every admin action is recorded: who did it, when, and what changed. Each member’s page shows the actions taken on their account; fee changes have their own history.
• Never share passwords, and never ask anyone for theirs. Use reset links.
• On a shared or public computer, untick “Keep me signed in” when you sign in, and click Sign out when you’re done. Anyone using a device you stay signed in on can open the admin.
• Card details never reach Ribbit.Deals: businesses pay on Stripe’s own page.
• When someone leaves the team, remove their admin access from their member page straight away.

13a. Backups & restore drill

Attempt limits: to stop password guessing, a member account allows 8 wrong sign-in attempts in 15 minutes (then waits 15 minutes, even for the right password; “Forgot password?” still works), and repeated sign-ups, password resets, invite checks and typed card codes are limited too. If a member says they’re locked out, they can wait 15 minutes or reset their password.

A backup only counts once it has been restored successfully. This section covers what must be backed up, how often, and a short drill to prove the backups work. First step: confirm in Plesk what is actually scheduled today; nothing in the app can see that.

What must be backed up

1. The database (px_rib138): members, businesses, deals, redemptions, statements, points, agreements and the audit trail. Everything that matters.
2. The production build’s settings file (.env in beta-laravel), especially APP_KEY. It encrypts the push-alert sending key and the sessions. Keep a copy in the founders’ password manager as well as in backups: if APP_KEY is lost, push alerts must be set up again and everyone is signed out.
3. Deal photos: beta-laravel/storage/app/private/media (unless MEDIA_ROOT in .env points elsewhere).
4. The member app’s files on ribbit.genxapp.org (they are not in Git). Its config.php holds the database password.

The production build’s code is in Git, so it can always be redeployed; its data and settings cannot.

Schedule (Plesk → Websites & Domains → Backup Manager → Schedule)

• Daily, overnight, including files and databases. Keep at least 14 daily and 8 weekly copies.
• Store a copy off the server (Plesk’s remote storage: FTP, Amazon S3, Google Drive or similar). A backup kept only on the same server is lost with the server.
• Before any deploy that changes the database (VS Code shows a new file in database/migrations), export the database first: Plesk → Databases → px_rib138 → Export Dump.

Restore drill (every 3 months, about 20 minutes)

1. In Plesk Backup Manager, download the most recent backup, or open it and choose to restore only the database into a new, empty database (for example px_rib138_drill). Never restore over the live database for a drill.
2. Open the drill database in phpMyAdmin and compare a few counts with the live one: users, businesses, redemptions, invoices. They should match as of the backup’s time.
3. Check the newest row in redemptions is from the night of the backup (proves the backup is current, not stale).
4. Confirm a recent deal photo is inside the backup’s files.
5. Delete the drill database. Note the date and result in the admin log or the founders’ shared notes.

If something is ever lost

Restore the database from the newest good backup (Backup Manager → the backup → restore the database only), then the deal-photo folder if needed. Redemptions made after that backup would be missing, and businesses aren’t billed for anything that isn’t in the database. Call your developer before restoring anything over the live site.

14. Where everything lives

The addresses on genxapp.org are interim; the permanent home is app.ribbit.deals.

15. Glossary

Verified redemption

A redemption confirmed by the member’s location and the business’s Ribbit card.

Void window

The 48 hours after a redemption during which the business can void it. After that it’s final and billable.

Performance fee

What a business pays per verified redemption: a flat amount, or a percentage of the typical purchase stated on the deal.

Operations fee

The monthly fee per business or per location.

Override

A performance fee an admin sets for one business, replacing its signed and category rates for new redemptions.

Held for pricing

A redemption whose fee couldn’t be calculated yet; it waits rather than being guessed.

Ribbit card

The counter card for each location: QR code plus typed code.

BPA

Business Participation Agreement, the agreement businesses accept; each version is numbered (BPA v1, v2…).

Revision history