Concepts

Lifecycle Areas

Retivo covers 5 lifecycle areas, each representing a type of intervention rather than a user's current stage. A single user can be targeted by playbooks from multiple areas simultaneously.

Lifecycle Areas vs. Lifecycle Stages

Lifecycle stages (new → onboarding → active → at_risk → churned → recovered) describe where a user IS in their journey. Lifecycle areas describe what KIND of intervention to apply. These are orthogonal — an active user can be targeted by retention AND upsell playbooks simultaneously.

Scoring Dimensions

Retivo computes three scores for each user:

These scores feed into playbook entry conditions. For example, a "Plan Limit Approaching" upsell playbook might require expansion_score >= 0.7 and engagement_score >= 0.6.

Win-back Timing

Churned users receive time-sequenced outreach at configurable intervals (default: 7, 30, 60 days after churn). Each interval uses a different playbook with escalating intensity:

1. Early win-back (7-14 days) — Gentle re-engagement, remind of value
2. Win-back offer (30-45 days) — Incentive or new feature highlights
3. Last chance (60-75 days) — Final outreach with feedback request

Test Mode

API keys starting with rt_test_ activate test mode. Test mode is designed for development, staging, and CI — the full pipeline runs, but no messages are delivered to real users.

When to use test keys:

• Development — Track events without sending real emails
• CI/CD — Verify pipeline behavior in automated tests
• Staging — Run realistic load without impacting users
• Demos — Show the full flow without side effects

Both live and test keys are created in Settings → API Keys.

Roles & Permissions (RBAC)

Retivo uses role-based access control with three roles:

Invite team members via the API:

curl -X POST https://retivo.ai/api/team/invite \
  -H "Authorization: Bearer rt_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "email": "alice@example.com", "role": "editor" }'

Invitations expire after 7 days.

Rate Limits

API requests are rate-limited per tenant based on your plan:

Every API response includes rate limit headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1743926400

When you receive a 429 response, wait until X-RateLimit-Reset before retrying. Use exponential backoff for resilient integrations.

If you need higher limits, upgrade your plan via Settings → Billing or the billing API.

Opt-Out

Every email sent by Retivo includes an unsubscribe link. When a user opts out:

1. Their opted_out flag is set to true
2. They are excluded from all future evaluation
3. No further interventions are created for them

The opt-out is permanent per-tenant unless manually reversed.

Checking Opt-Out Status

curl https://retivo.ai/api/customers/user-123 \
  -H "Authorization: Bearer rt_live_..."

The opted_out field in the response indicates whether the user has opted out.

Pausing vs. Opt-Out

Opt-out is user-initiated and permanent — the user chose to stop receiving messages. Pausing (via PUT /api/users/pause) is team-initiated and temporary — you can unpause at any time. Use pause for account reviews, migrations, or temporary holds.

Dry-Run

The dry-run API lets you test evaluation without side effects — no intervention is created and no message is sent.

curl -X POST https://retivo.ai/api/interventions/dry-run \
  -H "Authorization: Bearer rt_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "user_id": "user-123" }'

Response:

{
  "decision": {
    "action": "intervene",
    "playbook_id": "pb_abc",
    "channel": "email",
    "confidence": 0.82,
    "reasoning": "User hasn't completed onboarding in 5 days..."
  }
}

Use dry-run to:

• Validate playbook configurations before activating them
• Debug why a specific user is or isn't receiving interventions
• Preview AI reasoning before going live
• Automated testing — assert that your playbook rules trigger correctly for test scenarios