State machine
An athlete on your platform is always in exactly one of these states:
The subscribe CTA rides on teaser responses, so an athlete meets it when the trial expires or when they spend the day’s calls, not while the trial is answering in full.
The journey, narrated
1. You create the athlete and run their first activity calculation. You have synced an athlete from your database, maybe just their name and email. You call calculate for tomorrow’s 2-hour ride. Saturday answers with a band (“60-80 g carbs/hr”),profile_complete: false, a sorted list of missing fields, and an onboarding.url. The band is the answer, not a degraded one: Saturday will not compute an exact-looking number out of defaults. The athlete’s trial has not started either, so this call costs them nothing.
Your code: show the band, and surface the onboarding invite, a button like “Get your exact numbers (2 min)” linking to onboarding.url.
2. The athlete taps the invite.
They land on a Saturday page co-branded with your platform (“YOURAPP × SATURDAY”), greeted by first name. The page says how many questions are left and offers two paths: answer here, or get the free Saturday app, signing up with the same email they use on your platform so the accounts connect. Either works; the page is the faster first experience.
Your code: nothing. The page asks only what is missing, and skips anything you already sent, such as sex or weight.
3. They answer one question per screen.
Sweat level, saltiness, carb experience, the same questions Saturday’s own app asks, as tap targets. Every answer saves as it is given, so bailing at question 4 still leaves those 4 answers narrowing the bands. The link keeps working and they can come back.
4. The finish moment.
On the last answer, the page asks: “Can we show you fuel for one of your activities?” If they say yes and you have registered activity_link_template, they deep-link straight into your activity screen, where your integration now shows exact Saturday numbers. If not, the page shows their most recent activity’s exact targets alongside your fueling_path_copy (“In YourApp: open any activity, then the Fuel tab”), and returns them via your return_url.
Your code: register activity_link_template and fueling_path_copy on your partner account once. That is what turns Saturday’s finish screen into a hand-back into your product at the moment the athlete most wants to be there.
5. The webhook fires.
athlete.profile_completed arrives once. Their next calculation, and every one after, returns exact numbers, as long as the call also carries the activity’s intensity, thermal stress, meal timing, and race flag. The 30-day trial is running; the subscribe CTA handles conversion after that (Freemium Model).
Your code: on that webhook, refresh any cached athlete state, and consider marking the moment in your UI: “Your fueling numbers are now exact.”
The app path, narrated
Some athletes already use, or will prefer, the Saturday app. When their app account email matches the email you sent on the athlete record, Saturday links them and their app onboarding feeds your calculations, resolved live rather than synced, with nothing for you to build. Their app answers are never exposed to you through the API. If they turn on “share my fueling profile with {your platform}” in app settings, the profile values become visible to you as well. Tell your athletes: “use the same email as your {platform} account”. Matching is exact apart from case and whitespace, so a different address never links, and no error surfaces anywhere for you to catch.What to build, minimally
- Show
precision.messageand the invite button wheneverprofile_completeis false. - Register
activity_link_templateandfueling_path_copyonce. - Handle
athlete.profile_completed, if you want to mark the moment in your UI.