F72 extension — Onboarding 30-seat offer

Status: implemented behind fail-closed provider and store-activation gates; not approved for release Owner: F72 Freemium & Soft Paywall Surfaces: Android and iOS first-organization activation only Decision: a fixed 30-human-workspace-user package with a store-eligible seven-day trial, priced at USD 33/month or USD 360/year before tax

1. Decision summary

Lumi may show one acquisition offer immediately after a newly registered billing owner creates their first organization:

Google Play uses the exact USD 360 annual target. Apple’s nearest available US customer price point is USD 359.99/year; Apple surfaces and renewal disclosure must show that exact store charge.

The package is a 30-seat commitment and cap, not “from USD 1/user.” It does not prorate below 30 users and does not automatically sell an unpriced 31st seat. Lumi’s reserved system member is excluded; every active human organization member is currently AI-enabled and counts toward the cap. An organization needing more than 30 humans must use the normal plan-change path and loses this acquisition price for the replacement package.

The offer is not a hard paywall. An eligible leader may dismiss it and enter the Free workspace. The special products never appear on Lumi’s public pricing, durable in-workspace paywall, Settings, or normal change-plan catalog. A valid purchase can still renew and be restored after onboarding; “onboarding-only” limits Lumi’s merchandising, not the customer’s right to manage an existing subscription. Google Play can additionally enforce developer-determined offer eligibility. Apple does not provide an equivalent developer-determined gate for introductory offers and may surface an eligible introductory offer on the App Store product page; §4.4 records that platform boundary.

2. Why this requires a separate contract

The current repository cannot safely ship this by adding two hidden product IDs:

• Android and iOS currently know only the 5/10/20/50-seat lumi_ai_pro_* products.
• The dedicated TrialActivationScreen and TrialActivationView hardcode Starter/Pro/Ultimate prices and Vietnamese copy instead of rendering the live store selection.
• Both activation implementations can display one plan while purchasing another. Android chooses the smallest monthly product; iOS chooses the first monthly product.
• Backend store verification recognizes product identity and seat count but has no authoritative onboarding-offer grant. A caller could submit a special product outside onboarding.
• verify_store_purchase is currently a deterministic mock. Production launch remains blocked until Apple/Google verification and lifecycle notifications are real, as already required by F24.

Therefore availability must be enforced by the server and stores, not by client navigation.

3. Users and eligibility

Eligible

All conditions must be true:

1. The user has just completed their first organization setup in this account lifecycle.
2. Server subscription truth says can_manage_billing:true and status is neither active nor trialing.
3. The server returns an unexpired onboarding_30 grant for that user and organization.
4. The selected store account returns the matching product and is eligible for its exact free seven-day introductory offer.
5. The organization has never consumed or declined this offer.

Ineligible

Members without billing authority, invited users claiming an existing organization, additional organizations, active/trialing organizations, prior consumers, explicit dismissers, expired grants, and store accounts without the exact trial are ineligible. They enter the workspace directly.

Creating another organization must not mint another grant. Client clocks, local flags, route names, and a supplied offer_code are never eligibility evidence.

4. Lifecycle and server authority

4.1 Grant

After successful first-organization setup, the backend may atomically create one OnboardingOfferGrant:

One grant may exist per user for this offer, and one organization may consume it at most once. Issuance, decline, and consumption are idempotent and tenant-scoped.

4.2 Presentation

The client requests the offer only in the just-completed setup transition. It does not cache eligibility. An eligible response contains the two allowed product IDs and display metadata but no trusted price string. The store remains authoritative for localized price and trial eligibility.

• Explicit Continue with Free marks the grant declined; it can never be reacquired.
• App termination does not turn the offer into a returning-launch interstitial. The grant merely remains valid long enough to finish an already initiated store transaction.
• A pending store transaction may resume through normal purchase reconciliation without replaying the promotional screen.

4.3 Purchase and restore

Proposed product IDs:

• lumi_ai_pro_30_onboarding_monthly
• lumi_ai_pro_30_onboarding_annual

The purchase request binds {grant_id, organization_id, product_id}. The verification transaction must lock the grant and organization, verify the provider proof and exact product, reject expired, declined, consumed-by-another-transaction, cross-tenant, or mismatched-period requests, then create one 30-seat ai_pro subscription and consume the grant.

A direct call to store verification without the matching grant cannot authorize a Google developer-determined offer. Restore is different: a provider-verified original transaction may restore the already-owned subscription without a live grant, but cannot attach it to another organization or mint a second trial.

4.4 Apple acquisition boundary

App Store introductory-offer eligibility is controlled by Apple at the subscription-group/account boundary; Lumi cannot attach its server grant to Apple’s eligibility decision. Lumi therefore:

• queries and merchandises the two special products only on the eligible onboarding surface;
• does not promote them as in-app purchases in App Store Connect;
• still honors and safely attaches any valid Apple transaction for those products, even if the onboarding grant is absent or expired, because the customer may already have been charged;
• uses the grant as analytics/presentation evidence on iOS, not as grounds to deny a valid purchase.

If strict store-level “only purchasable during Lumi onboarding” is a non-negotiable commercial requirement, this iOS package cannot ship as an ordinary introductory offer. Product must accept the narrower in-app merchandising guarantee or choose a different Apple commercial mechanism after App Review/payment-policy validation.

5. Store configuration and money truth

The product stores own billing currency, localized price, tax treatment, trial eligibility, renewal, cancellation, refund, and revocation. Required console configuration:

• monthly product: USD 33/month base price;
• annual product: USD 360/year base price;
• exact zero-price P7D offer: Google Play uses a developer-determined offer tagged lumi-onboarding-30 and lumi-trial-7d; StoreKit uses an equivalent introductory offer;
• products unavailable to the normal catalog surface.

The app may show the USD unit-price explanation only when the returned storefront price is USD and matches the configured total. In another currency it shows the localized total and cadence from the store, plus “includes 30 AI users”; it must not divide a converted/rounded price and present the result as a contractual USD unit rate.

If either product is absent, its price is inconsistent, or the exact trial is unavailable, the special offer fails closed: do not claim a trial and do not substitute a different product. Enter the Free workspace; normal pricing remains available later.

6. Experience contract

Previous state: first organization setup completes. Current state: one full-screen, dismissible activation offer. Next state: provider-confirmed subscription or the usable Free workspace.

The screen answers four questions without a comparison grid:

1. What is included? 30 AI users and the named AI Pro benefits from server plan truth.
2. What do I pay? The total charge is visually primary.
3. When do I pay? Today is zero only when live store eligibility proves it; show trial end date and first renewal amount/cadence before the CTA.
4. Can I leave? Show automatic-renewal and cancellation terms and a visible Continue with Free action.

Default to annual only when both choices are loaded and the annual total is visibly stated. The annual badge says Save USD 36/year; it must not say “best value” or imply scarcity. Selecting a cadence updates one coherent offer model: displayed total, renewal sentence, CTA semantics, and purchased product ID.

Suggested English copy:

• Title: Start with your whole team
• Supporting line: 30 AI users included. Try Lumi for 7 days, then choose how you pay.
• Annual price: $360/year total · $1/user/month equivalent
• Monthly price: $33/month total · $1.10/user/month
• CTA: Start 7-day free trial
• Secondary: Continue with Free

Vietnamese copy must be written natively, not assembled from English fragments. All strings live in platform localization resources. The layout supports 320–430 pt/dp widths, Dynamic Type/font scaling, screen readers, focus order, switch control, reduced motion, safe areas, and software keyboard without hiding either action. Touch targets are at least 44×44 pt / 48×48 dp.

7. API shape (proposed)

GET /api/billing/onboarding-offer/

{
  "eligible": true,
  "grant_id": "uuid",
  "offer_code": "onboarding_30",
  "expires_at": "2026-08-06T03:00:00Z",
  "seats": 30,
  "products": {
    "monthly": "lumi_ai_pro_30_onboarding_monthly",
    "annual": "lumi_ai_pro_30_onboarding_annual"
  }
}

Ineligible responses return 200 {"eligible":false} and no product IDs. The endpoint is authenticated and scoped to the active organization.

POST /api/billing/onboarding-offer/{grant_id}/decline/ is idempotent.

POST /api/billing/store/verify/ adds offer_grant_id for these two product IDs. It is mandatory for Google offer-token selection and verification. On Apple, a valid signed transaction must be honored even when presentation-grant evidence is missing; the server records that discrepancy for review rather than withholding paid entitlement. The server ignores client-supplied prices, seat counts, trial dates, and eligibility booleans.

8. Analytics and support

Record privacy-safe, append-only events with organization/user pseudonymous IDs: offer_eligible, offer_presented, cadence_selected, checkout_started, checkout_cancelled, offer_declined, purchase_pending, trial_started, and verification_failed. Never log receipt, purchase token, customer content, or raw store-account identity.

Primary funnel: eligible → presented → checkout started → provider-verified trial. Guardrails: explicit-dismiss rate, verification failure rate, refund/revocation rate, and support contacts. Presentation is not conversion; store upload is not activation.

Implementation note: offer_eligible and offer_declined are wired with pseudonymous IDs. The remaining native checkout and provider-lifecycle events are an explicit non-blocking contract gap; they must be completed before conversion reporting is treated as trustworthy.

9. Acceptance criteria

1. Only a server-eligible, first-organization billing owner can retrieve the special product IDs.
2. A Google developer-determined offer without a matching locked grant fails before subscription mutation; a valid Apple transaction is honored and discrepancy-ledgered.
3. Monthly always means 30 seats and a store total of USD 33/month; annual always means 30 seats and USD 360/year in a USD storefront.
4. Trial copy and CTA appear only for the exact live, eligible P7D zero-price offer.
5. Displayed cadence, renewal disclosure, and purchased product are the same selected object.
6. Dismissal enters Free, permanently declines the grant, and never replays the offer.
7. The special products are absent from every normal pricing/change-plan surface.
8. Existing subscribers can restore and manage the acquired subscription without reacquiring the offer; cross-organization restore fails closed.
9. A 31st active human member cannot be silently added or billed. Direct invite and invitation-link acceptance return a stable capacity conflict while preserving the invitation; standard plans retain their existing membership behavior.
10. Provider verification, renewal, cancellation, refund, revocation, trial expiry, and server notification handling are live-proved before production activation.

10. Explicit non-goals

• No hard payment gate, countdown timer, fake scarcity, or repeated interstitial.
• No web checkout or public promotional URL in v1.
• No per-seat proration, seat overage, custom quote, coupon stacking, or mid-cycle migration design.
• No client-authored price, eligibility, entitlement, or trial lifecycle truth.
• No launch while F24 store verification remains in mock mode.

11. Release gates and remaining commercial decisions

The implementation resolves the entitlement boundary as 30 active, non-system organization members and blocks the 31st membership. Product/Finance must still confirm before activation:

1. whether taxes are included or added by each storefront;
2. countries/currencies where the offer is enabled and the approved localized price tiers;
3. ownership of refunds and customer support.

The contract, plan, runbook, diagrams, and registry travel with the implementation. A Markdown spec, unit test, draft store product, or mocked receipt is not release evidence.

Store-console execution details and API automation boundaries live in the proposed store setup runbook.