RevHold is an AI-powered business assistant and churn detection tool that helps SaaS founders prevent customer churn by analyzing real usage data and identifying at-risk customers before they leave.

How does the churn detection tool work?

Our AI analyzes customer usage patterns, engagement metrics, and behavioral signals to predict churn risk. You can ask questions in plain English and get actionable insights about which customers are at risk and why.

Can RevHold help identify upsell opportunities?

Yes, RevHold identifies customers who are ready for upgrades based on their usage patterns, feature adoption, and engagement levels, helping you maximize revenue retention.

Documentation

RevHold is an AI business assistant that helps SaaS founders understand churn and identify upsell opportunities by analyzing real usage data and billing patterns.

Who is this for?

• SaaS founders who need clarity, not dashboards
• Product teams tracking feature adoption
• Growth teams identifying expansion opportunities
• Anyone who wants to ask questions about their usage data

What problems does it solve?

• Why did a customer churn?
• Which users are ready to upgrade?
• What features drive retention?
• Which segments have the highest engagement?

Getting Started

Quick Start

Get up and running with RevHold in minutes. Follow these steps to send your first usage event and ask your first AI question.

1Create an account

2Get your API key

After signing up, navigate to your dashboard to find your API key. Keep it secure.

3Send your first usage event

Track user activity by sending usage events to RevHold:

curl -X POST https://www.revhold.io/api/usage \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_123",
    "eventName": "feature_used",
    "eventValue": 1,
    "timestamp": "2025-01-02T10:00:00Z"
  }'

4Ask your first question

Get insights from the AI about your usage data:

curl -X POST https://www.revhold.io/api/ai \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Which users are most engaged this week?"
  }'

Authentication

All API requests require authentication using your API key. Include it in the Authorization header as a Bearer token.

HTTP Header

Authorization: Bearer rh_1234567890abcdef

Security Note

Never expose your API key in client-side code. Always make API calls from your server.

Server SDKs (Optional)

Official SDKs provide a cleaner developer experience with type-safety, automatic retries, and better error handling. However, SDKs are completely optional — you can use direct API calls if you prefer (see examples in Quick Start above).

✓ With SDK

Type definitions, automatic formatting, connection pooling, helpful errors

✓ Direct API

Simple HTTP calls, no dependencies, works in any language

Installation

npm install @revhold/node
# or
yarn add @revhold/node

Basic Usage

import { RevHold } from '@revhold/node';

const revhold = new RevHold({
  apiKey: process.env.REVHOLD_API_KEY,
});

// Track a usage event
await revhold.trackEvent({
  userId: 'user_123',
  eventName: 'document_created',
  eventValue: 1,
});

// Ask AI a question
const insight = await revhold.askAI({
  question: 'Which users are most engaged this week?',
});
console.log(insight.answer);

Batch Events

Send multiple events in one request for better performance:

await revhold.trackBatch([
  { userId: 'user_1', eventName: 'feature_used' },
  { userId: 'user_2', eventName: 'document_created' },
  { userId: 'user_3', eventName: 'export_completed' },
]);

Error Handling

try {
  await revhold.trackEvent({
    userId: 'user_123',
    eventName: 'feature_used',
  });
} catch (error) {
  if (error.status === 429) {
    console.error('Rate limit - retry after 60s');
  } else if (error.status === 402) {
    console.error('Plan limit reached - upgrade');
  } else {
    console.error('Error:', error.message);
  }
}

Other Languages

Don't use Node.js or Python? No problem! You can make direct HTTP requests from any language. See the Quick Start section above for cURL examples, or check the API Reference for full details.

Official Ruby, PHP, and Go SDKs coming soon. Request a language.

Sending Usage Events

Usage events are the core of RevHold. They represent actions your users take in your product. The more events you send, the better the AI can understand patterns and provide insights.

What are usage events?

Usage events track specific actions users take in your application. Examples include:

• Feature usage (e.g., "created_report", "sent_email")
• User activity (e.g., "logged_in", "viewed_dashboard")
• Business events (e.g., "trial_started", "subscription_upgraded")

Required fields

Field	Type	Description
userId	string	Unique identifier for the user
eventName	string	Name of the event (e.g., `"feature_used"`)
eventValue	number	Numeric value (optional, defaults to 1)
timestamp	ISO 8601	When the event occurred

Example payload

JSON

{
  "userId": "user_abc123",
  "eventName": "document_created",
  "eventValue": 1,
  "timestamp": "2025-01-02T14:30:00Z"
}

Best practices

• Use consistent naming for events (e.g., snake_case)
• Send events in real-time or near real-time
• Include context in event names when relevant
• Track both successful and failed actions
• Use eventValue to track quantities (e.g., emails sent, reports generated)

AI Insights

RevHold's AI analyzes your usage data and billing information to answer questions in plain English. No SQL required, no complex queries—just ask.

What the AI analyzes

Usage patterns

Frequency, recency, feature adoption, engagement trends

User behavior

Active vs. inactive users, power users, at-risk segments

Billing data

Subscription status, MRR, churn events (when Stripe is connected)

Correlations

Features that predict retention, upgrade triggers, churn signals

Example questions

Which users have the highest engagement this month?

Why did user_123 churn last week?

What features do power users use most?

Which trial users are most likely to convert?

Show me users who haven't logged in for 7 days

What's the correlation between feature X and retention?

What responses look like

The AI provides clear, actionable answers with relevant data points:

Example Response

"Based on your usage data, 5 users are highly engaged this week:

• user_123: 47 events, using feature X daily
• user_456: 39 events, strong adoption of feature Y
• user_789: 32 events, consistent daily logins

These users show strong product-market fit indicators and may be good candidates for upsell or case studies."

Free Plan Limit

Free plan accounts are limited to 20 AI text questions. Upgrade for unlimited AI text and voice access.

Billing & Stripe Integration

RevHold can analyze your billing data alongside usage patterns to provide deeper insights about churn, expansion revenue, and customer lifetime value.

Why connect Stripe?

• Understand which usage patterns correlate with upgrades
• Identify at-risk customers before they churn
• Track MRR alongside product engagement
• Get AI insights about billing events and subscription changes

How it works

Connect via OAuth

Use Stripe's secure OAuth flow to authorize RevHold. No API keys required.

Read-only access

RevHold only reads subscription and payment data. We never modify your Stripe account.

Automatic sync

Billing data syncs automatically. The AI can answer questions combining usage and revenue.

Stripe is optional

You can use RevHold without connecting Stripe. Usage insights work independently of billing data.

Limits & Errors

Plan limits

Resource	Free Plan	Paid Plans
AI text questions	20 total	Unlimited (fair-use)
Voice AI	Not available	30-300 min/month by plan
Usage events	Unlimited	Unlimited
Data retention	90 days	Unlimited

See our pricing page for detailed plan comparison. Additional voice minutes are $0.20/min.

Rate limits

• Usage events: 1,000 requests per minute
• AI questions: 10 requests per minute
• API key: Share rate limits across all endpoints

Common error messages

401 Unauthorized

Invalid or missing API key. Check your Authorization header.

402 Payment Required

Free plan limit reached. Upgrade your plan to continue using AI insights.

429 Too Many Requests

Rate limit exceeded. Wait 60 seconds before retrying.

400 Bad Request

Invalid request body. Check that all required fields are present and correctly formatted.

Frequently Asked Questions

Yes. All data is encrypted in transit and at rest. We use industry-standard security practices and never share your data with third parties. Your usage data is only accessible to you and used exclusively to power your AI insights.

No. We never use your data to train AI models. Your usage events and questions remain private and are only used to generate insights for your account. We use third-party AI providers who are contractually prohibited from training on your data.

Absolutely. Stripe integration is completely optional. You can get full value from RevHold by analyzing usage data alone. Connect Stripe only if you want billing insights combined with usage patterns.

If you cancel your account, all your data is deleted within 30 days. You can also request immediate deletion by contacting support. We'll provide a data export if needed before deletion.

The AI analyzes your actual usage and billing data to provide evidence-based insights. Accuracy improves with more data points. We recommend sending comprehensive usage events and giving the system at least a few weeks of data for the most reliable insights.

Yes. You can request a full data export at any time from your dashboard. We'll provide your usage events and AI conversation history in JSON format.

No. The free plan includes 20 AI text questions as a one-time allocation. Once used, you'll need to upgrade to a paid plan for unlimited text questions and voice AI access. Usage event tracking remains unlimited on all plans. Your data is preserved when you upgrade.

You'll receive a 429 error response with a Retry-After header indicating when you can make requests again (typically 60 seconds). Rate limits are per API key and reset every minute. If you consistently hit limits, contact support to discuss higher limits.

Billing data syncs within 5 minutes of connecting your Stripe account. Historical data (past 12 months) is imported immediately. Real-time events like new subscriptions, upgrades, and cancellations sync automatically. If Stripe is not connected, the AI can only analyze usage patterns without billing insights.

Yes. You can delete individual events or bulk delete events by user ID through the dashboard. Deleted events are removed from AI analysis immediately. This is useful for testing data cleanup or removing incorrect events.

All timestamps must be in UTC (ISO 8601 format ending with 'Z'). The API will reject timestamps without timezone information or with local timezones. The AI automatically handles date ranges and time-based queries using UTC.

Ready to get started?

Get Started Free View API Reference