Birthday Add-On

🧾 History

📕 About

🧭 How This Fits With Other Birthday-Related Work

We have three different things touching the word “birthday” right now. Each is scoped separately so work doesn’t overlap or get confused in standup.

One thing regardless: all three must use consistent naming in analytics (Birthday Add-On, Birthday Landing Page, Birthday Diary Card) so dashboards don’t end up three ways labeled “birthday.”

📦 v1 Scope (Revised)

Decision (July 2026): hh-pegasus (diner-facing frontend) is currently out of reach. v1 ships only the data-layer and restaurant-facing surface. Diner-facing flows are deferred and will follow a separate workstream once hh-pegasus is back in scope.

In scope (this v1)

Deferred (gated on hh-pegasus access)

birthday_addon_created event is measurable in v1 — fires from book-bite when a restaurant creates a birthday add-on, no pegasus dependency.

Implications for success metrics

Bottom line: in v1, the only top-line metric that moves is “restaurant self-service adoption”. The attach-rate, cannibalization, and checkout-reliability metrics are unblocked the moment hh-pegasus ships the diner-facing flows. Tracking for these deferred metrics should start fresh at pegasus release, not retroactively from v1 launch.

📕 Glossary

Vocabulary for terms unique to this PRD. Same terms must be used across hh-server, hh-pegasus, partner portal, and analytics — distinct, consistent naming is the whole point.

Add-On:

A supplementary item a restaurant sells alongside a booking, priced per-person or per-item, with its own date range, image, and limits. Stored in the add_ons table.

Avoid: “package” (means Party Pack), “promotion”, “extra” (overloaded with delivery upsells).

Birthday Add-On:

An add-on (in add_ons table) the restaurant has marked as occasion-gated for birthdays, via add_on_type = 'birthday'. Surfaced in the fixed “Birthday Celebration” section on the restaurant page, drives the discovery icon on restaurant cards, and is excluded from the admin catalog list.

Avoid: “birthday package” (already means Party Pack), “birthday perk” (overlaps with the free variant below).

Premium Birthday Add-On:

A birthday add-on priced above zero. Appears in the Birthday Celebration section and is treated like a standard add-on at checkout.

Avoid: “paid birthday package”, “birthday upsell”.

Free Birthday Add-On:

A birthday add-on priced at zero. Hidden from the store page and cart; only selectable after the diner picks “Birthday” as the booking occasion at checkout. The restaurant sets their own daily limit on how many they’ll give away.

Avoid: “comp”, “freebie”, “gift” (gift has a separate voucher meaning).

Occasion:

A diner-declared context for a booking — birthday, anniversary, business dinner, etc. — picked from a fixed selector at checkout. Used to unlock occasion-gated features (free add-ons) and to drive CRM reminders via the separate Occasion Vault initiative.

Avoid: “event” (overloaded), “celebration” (overlaps with Celebration Landing Pages).

Occasion Vault:

A separate HH initiative (codename “The Diary”) that stores each user’s occasions in their profile and sends CRM reminders roughly two weeks before the date. Upstream of any booking. Shares the “occasion” vocabulary with checkout but solves a different problem (pre-booking nudge vs. in-checkpoint unlock).

Celebration Landing Page:

A separate SEO/discovery surface listing restaurants whose tags fit a celebration theme (Birthday, Party Pack, Private Room). Built from the same restaurant-tagging system that powers other themed landing pages (e.g. Romantic Dinner). Parallel to, not downstream of, birthday add-ons.

Discovery Icon:

The small icon shown on a restaurant card when the restaurant has at least one active birthday add-on. Pulled dynamically from that add-on’s own cover image, not a fixed cake graphic. Multiple icons can show if the restaurant has multiple birthday add-ons.

Avoid: “birthday badge” (overloaded — the partner-portal creation screen also calls itself a “badge”), “cake icon” (no longer accurate since the icon is dynamic).

Add-On Type (add_on_type):

The classification column on add_ons that distinguishes occasion-gated add-ons from standard ones. Currently only standard and birthday. Reserved so other occasion types can be added later without schema changes.

Commission Inheritance:

The rule for setting commission on a new add-on (or package) when the restaurant has no explicit override: take the rate from the restaurant’s most recent active, non-partner-created package of any type; if none exists, fall back to a flat 12.50%. Already implemented for package creation; birthday add-ons plug into the same inheritance.

Avoid: “default commission” (the 12.50% is a fallback, not a default override).

🧠 Design Decisions

🎯 User Stories & Functional Requirements

Flow 1: Spotting a Birthday-Friendly Restaurant (Discovery Icon)

When exactly should the icon show?

Deep link

Our app is a wrapper around web pages (universal links), so one web approach covers web, mobile web, and app.

Link shape: web.hungryhub.com/{lang}/restaurants/{restaurant_slug}?section=birthday-celebration

Restaurant page already scrolls to specific sections (used for on-page tabs). What’s new: read section value from URL on page load, trigger scroll once birthday section has actually rendered (it may load slightly later than rest of page). If section not found: wait a few seconds before giving up; if genuinely gone, land normally at top; if URL value broken, ignore silently.

Flow 2: Browsing and Picking a Paid Birthday Add-On on the Restaurant Page

Flow 3: Viewing an Add-On’s Details

Reuses existing add-on detail page (cover image, description, what’s included, refund policy). Nothing birthday-specific here.

Flow 4: Adding to Cart

Cart itself needs nothing new. What’s new: exactly one birthday add-on, quantity one, can sit in cart at a time. Client-side convenience logic with checkout as the real gate (Flow 5). This rule applies only to birthday add-ons; other regular add-ons unaffected.

Watch for: existing rule that blocks mixing add-ons with certain ticketed packages still works correctly once birthday add-ons are in the mix.

Flow 5: Checkout & Confirming the Booking

Flow 6: Selecting Birthday as the Occasion Unlocks the Free Add-On

Flow 7: Booking Confirmation & Reporting

A birthday add-on is treated exactly like any other add-on everywhere in reporting, booking list, booking detail, exports, and analytics — both admin dashboard and partner portal. No new design, no special highlighting, no separate section. Deliberate call, not oversight.

Free item reads as “Free,” not “฿0.00” or blank, in confirmation screen and email.

Flow 8: Creating & Editing a Birthday Add-On (Partner Portal)

This is genuinely new: the partner portal’s current add-on screen is read-only (list only, no create/edit form). This is a real screen to design and build from scratch.

Flow 9: Picking a Birthday Add-On When Staff Manually Create / Edit a Booking (Partner Portal)

Different screen from the diner-facing store page and cart. Partner portal’s own booking create/edit tool has its own add-on selection component. Same core rule applies here: once staff pick one birthday add-on, the other birthday add-on(s) in the list become inactive / unselectable, so staff can’t attach two to the same booking. Non-birthday add-ons in the list are unaffected.

Watch for: needs its own implementation, separate from the diner-facing cart logic in Flow 4 — different screen with its own add-on selection component.

UX detail: see the navigation hub for the BE integration doc that defines the selection-gate behavior.

🧠 Rules

• Exactly one birthday add-on per booking, quantity one. Applies regardless of how many birthday add-ons a restaurant has. Other add-ons unaffected. App swaps instantly for feel; checkout is the authoritative gate (matters for stale sessions, multiple tabs, direct API hits).
• A restaurant can have at most one free (฿0) birthday add-on configured at any time. The partner-portal list page shows “Free Birthday Add-On (Max 1)” and the server enforces the cap at creation time.
• A ฿0 add-on behaves differently, on purpose. Hidden from store page and cart. Selectable only after diner picks Birthday occasion at checkout (Flow 6). No extra validation beyond that.
• Free item capped at one per booking. Restaurant sets own daily limit on how many they’ll give away.
• No verification of actual birthday. Self-declared, same as any other add-on or occasion.
• Vouchers work the same as any other add-on — no special exclusion. Treated as a standard add-on everywhere (Flow 7). Still sits outside the separate demand-based pricing system (real edge case).
• Created only through partner portal, not admin. Restaurants set these up themselves. Not in the regular admin add-on list.
• Commission follows package-creation inheritance — see 🧠 Design Decisions above.
• Section title and description are fixed — no setting anywhere, hardcoded in app.
• Discovery icon is dynamic — pulled from whichever birthday add-on(s) restaurant has, not one universal graphic. Multiple icons if multiple add-ons.
• Available all day, every day it’s active. No opening-hours / time-of-day schedule. On or off for whatever active date range restaurant sets, no intraday scheduling.
• Group-login accounts may create and edit birthday add-ons per restaurant, but cannot select them while creating or editing a booking on a customer’s behalf.

Why the free item works the way it does

The restaurant’s gesture, not HH subsidizing. Restaurant sets up ฿0 add-on = their own choice, their own cost to bear (like comping something today without our involvement). Because it’s the restaurant’s cost, they’re the natural check on how far it goes — they set own daily limit, can turn off any time. Gating behind “diner already told us it’s a birthday booking” naturally limits to people in a birthday-booking moment, not opportunistic grabs. If abused post-launch: tighten the daily limit, don’t rethink the approach.

📊 How We’ll Know If This Worked

~10M users/year, ~20k daily app users — goals sized for v1.

Events we’ll track

These names must be distinct from anything Occasion Vault or Celebration Landing Pages use.

⚠️ Risks & What We’re Depending On

What has to be done before launch (v1 scope — see 📦 v1 Scope (Revised))

Implementation-status note (August 6, 2026): the table above is the original launch-planning snapshot and its historical Not started values are not a current code-status board. The current backend/API verification is recorded in the HHServer KB contract section (§29). Backend staging verification is green for the focused birthday, booking add-on, existing add-on, pricing, and reservation specs. Native birthday error translations and explicit zero-price/dynamic-pricing regression coverage remain launch-preparation items; diner-facing Pegasus flows remain intentionally deferred under the v1 scope decision.

Items moved to v2 (gated on hh-pegasus access)

🚀 Getting This Live

On the trade-offs we considered

Rollout plan

• Feature flag: ff_birthday_add_on_v1, turned on restaurant-by-restaurant so we can ramp gradually.
• Internal testing (week of July 20): our own team creates test birthday add-ons through the partner portal and runs the full flow end-to-end, including the pricing test.
• Small rollout (Aug 3–7): partner-portal screen opens to a small group of restaurants across all three markets — catch usability issues in the creation flow early. Matters more than before since restaurants are now doing this themselves.
• Wider rollout (Aug 10–14): opens up to more restaurants; icon goes live on listing surfaces once there’s enough real inventory to show.
• Full launch (Aug 17–20): everyone, targeting August 20.

What can / can’t slip

The partner-portal creation screen can’t slip — it’s the foundation everything else sits on. The discovery icon is the one piece that could launch a week or two late if needed, without blocking the core experience.

🔍 Still Open

📋 What We’re Not Doing (For Now)

• Letting diners filter / search by “has a birthday add-on” — touches search infrastructure, a bigger separate project.
• Letting restaurants configure this through the admin dashboard, or letting HH staff create these on a restaurant’s behalf — partner portal is the only path, by design.
• Giving these add-ons any special, more prominent treatment in restaurant-facing booking lists, reports, or exports — deliberately regular add-on everywhere in reporting.
• Verifying anyone’s actual birthday, or sending reminders about it — separate Occasion Vault work.
• A big new homepage entry point beyond the restaurant-card icon — no dedicated birthday landing tab in this phase.
• Any diner-facing eligibility check or minimum spend to unlock the free add-on beyond picking Birthday as the occasion.
• A settings screen for editing the Birthday Celebration section’s title / description — fixed copy, not configurable by anyone.

❓ FAQ

(placeholder — populate post-launch from support tickets / partner feedback)