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:

Decision quota: Every AI evaluation, /decisions/recommend call, and external action dispatch counts as one decision. This ensures compute costs scale with your plan.

External action types: Available on Growth and above. Starter plans can receive webhook events but cannot register action types.

Partner customers: Available on Scale and above. Each child tenant gets its own tracked user and decision limits.

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

External Actions

External actions extend Retivo's execution layer beyond its built-in channels (email, in-app, webhook, CRM). When an external platform like Smile.io or Gameball registers action types, Retivo's decision engine can recommend and dispatch those actions — "grant 500 points" or "unlock a badge" — to the right user at the right time.

The flow: external system registers capabilities → Retivo's AI decides when to use them → action dispatched via webhook or native client → external system reports outcome → Retivo learns.

See External Integrations for the full integration guide.

Action Types vs. Channels

Channels (email, in_app, webhook, crm) are Retivo's built-in delivery mechanisms. External action types (grant_points, unlock_badge, trigger_campaign) are capabilities provided by external systems. The decision engine chooses between both.

Outcome Learning

When external systems report action outcomes (completed, ignored, rejected), Retivo's learning layer extracts memories — the same way it learns from intervention outcomes. "Granting points after onboarding works for this user segment" becomes a reusable signal.

Partner Model (B2B2C)

Platforms that embed Retivo can operate as partners — provisioning isolated tenants for each of their customers with shared integrations and cross-customer intelligence.

Partners use the partner API key permission to access the Partner API (/api/partners/*). See External Integrations — Partner Integration for details.

Cross-Customer Learning

When a partner has multiple customers, Retivo's learning layer sees patterns across all of them. What works for Merchant A improves decisions for Merchant B — without sharing any customer data between tenants. The learning is aggregated and anonymized, similar to how the global benchmark system works.