> ## Documentation Index
> Fetch the complete documentation index at: https://cofounder.appeeky.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Monetization Experiments (RevenueCat)

> Move from read-only pricing intelligence to acting on it — read RevenueCat offerings & experiments, promote a winning offering (gated), and open pricing hypotheses.

# Monetization Experiments (RevenueCat)

The agent already reads pricing intelligence (your entry-price percentile vs
competitors) and cross-platform revenue. This capability lets it **act** on
monetization instead of only observing it — via RevenueCat.

## What the agent reads

Each run the collector reads **synced** RevenueCat overview + chart KPIs from
`revenuecat_overview_snapshots` / `revenuecat_chart_daily_metrics` (nightly
Trigger.dev sync — same pattern as ASC). Offerings and experiments are still
enriched live when credentials are connected (best-effort, so a permission gap
never blocks the revenue overview):

* **Offerings** — every offering, which one is **current**, and package counts.
  This is the monetization write surface.
* **Experiments** — the price/paywall A/B tests you set up in the RevenueCat
  dashboard, their status, and (for running/stopped tests) a summary of the
  leading variant.
* **Trial→paid conversion** — the latest conversion rate, feeding the
  auto-hypothesis logic.

## What the agent can write

**One reversible operation: promote an offering to "current."**

When a RevenueCat experiment is *stopped* with a clear, adequately-powered
winner, the agent proposes a `revenuecat_experiment` action (operation
`promote_offering`) that sets the winning offering as the project's current
offering — rolling the winner out to everyone. It's reversible: promoting the
previous offering rolls it back.

### Always gated

A monetization write moves real money and is hard to undo cleanly, so
`revenuecat_experiment` **always** requires your explicit approval — even at the
highest autopilot level, and even if you've added it to auto-approve types. It
never runs unattended.

## What it deliberately does NOT do

* **It can't create experiments.** RevenueCat's API has no experiment-create
  endpoint — you set experiments up in the RC dashboard. The agent reads and
  promotes winners; it doesn't launch tests.
* **It can't change App Store prices.** App Store IAP price *tiers* live in App
  Store Connect, not RevenueCat. A raw price change is an ASC concern. The RC
  lever here is *which offering serves*, not the store price itself.

## Auto-hypothesis engine

When the pricing percentile + trial→paid conversion suggest a monetization gap
(e.g. you're far below the competitor median with weak conversion, or far above
with high churn), the agent opens a **hypothesis** (`metricPath:
rc.trial_conversion` / `rc.mrr`) with a concrete test strategy rather than
guessing a price. You then run the experiment in the RevenueCat dashboard, and
the agent promotes the winner once the test concludes.

## The loop

1. **Read** — offerings, experiments, trial conversion, pricing percentile.
2. **Hypothesize** — open a pricing/paywall hypothesis when the numbers warrant.
3. **Promote (gated)** — when an experiment produces a winner, propose promoting
   the winning offering; you approve.
4. **Measure** — the promotion is recorded as a `pricing` experiment in memory
   (expected metrics: MRR, revenue, active subs, trial conversion) and its
   outcome is reconciled into the decision log after the measurement window.

## Requirements

* **RevenueCat connected** (Settings → Integrations). Reads use your existing
  secret key; the write reuses the same credentials.
* Experiments must be created in the RevenueCat dashboard for the agent to read
  results and promote winners.