SDK DOCUMENTATION

Rebutiq Docs

Everything you need to integrate Rebutiq into your SaaS application. From a single script tag to a full REST API — start collecting dispute evidence in under 10 minutes.

Installation

There are three ways to integrate Rebutiq depending on your stack. The JavaScript SDK is the fastest way to get started — just drop in a script tag. For server-side tracking, use the npm package or call our REST API directly.

Method	Use case	Setup time	Description
Script tag	string	~2 min	Drop into any HTML page. Auto-captures page views, clicks, scroll depth.
npm package	string	~5 min	React, Vue, or Node.js. Type-safe, tree-shakable, SSR-compatible.
REST API	string	~10 min	Any language. Send events, identify users, check risk scores via HTTP.

JAVASCRIPT SDK

Script tag installation

Add the Rebutiq snippet to your HTML <head> tag. The SDK loads asynchronously and will not block page rendering. It begins capturing page views, clicks, and session data immediately.

index.html

<!-- Add before </body> -->
<script src="https://cdn.rebutiq.com/sdk.js"></script>
<script>
  Rebutiq.init({ apiKey: 'rbq_proj_YOUR_KEY' })
</script>

Once installed, the SDK auto-captures: page views, click events, scroll depth (25%, 50%, 75%, 100%), session duration, rage clicks (3+ rapid clicks in 500ms), form interactions, and copy-paste events. No additional configuration needed.

Rebutiq.init(options)

If you need more control over initialization (e.g., disabling auto-track or setting a custom API endpoint), use the programmatic init method instead of the script tag attributes.

app.js

Rebutiq.init({
  apiKey: 'rbq_proj_YOUR_KEY',
  autoTrack: true,
  trackScrollDepth: true,
  trackRageClicks: true,
  trackFormInteractions: true,
  trackCopyPaste: true,
  endpoint: 'https://api.rebutiq.com'  // optional, defaults to this
})

Param	Type	Required	Description
apiKey	string	Yes	Your project API key. Found in Dashboard > Settings > API Keys.
autoTrack	boolean	No	Enable automatic page view and click tracking. Defaults to `true`.
trackScrollDepth	boolean	No	Track scroll milestones at 25%, 50%, 75%, 100%. Defaults to `true`.
trackRageClicks	boolean	No	Detect and report rage click patterns. Defaults to `true`.
trackFormInteractions	boolean	No	Track form field focus, blur, and submit events. Defaults to `true`.
trackCopyPaste	boolean	No	Track copy and paste events on the page. Defaults to `false`.
endpoint	string	No	Custom API endpoint. Defaults to `https://api.rebutiq.com`.

Rebutiq.identify(traits)

Call identify() after a user logs in or signs up. This links their browser session to their Stripe customer ID, which is critical for mapping activity to dispute evidence. Always pass stripeCustomerId if you have it.

auth.js

// Call after login or signup
Rebutiq.identify({
  userId: 'usr_8f2k9d',
  email: 'jane@acme.com',
  name: 'Jane Cooper',
  stripeCustomerId: 'cus_Qz8xfR4kL2m',
  plan: 'pro',
  createdAt: '2026-01-15T09:22:00Z'
})

Param	Type	Required	Description
userId	string	Yes	Your internal user identifier. Must be unique and consistent.
email	string	Yes	User's email address. Used for matching Stripe events.
stripeCustomerId	string	Yes	Stripe customer ID (cus_xxx). Links activity to payments.
name	string	No	User's display name. Included in evidence narratives.
plan	string	No	Current subscription plan. Useful for evidence context.
createdAt	string	No	ISO 8601 account creation date. If omitted, we use first-seen timestamp.

Rebutiq.track(event, properties)

Track custom events that strengthen your dispute evidence. While the SDK auto-captures most interactions, explicit tracking of key moments (terms accepted, feature used, export downloaded) dramatically increases your win rate.

events.js

// Track terms of service acceptance
Rebutiq.track('terms.accepted', {
  version: 'v2.1',
  url: 'https://app.example.com/terms'
})

// Track a core feature interaction
Rebutiq.track('feature.used', {
  feature: 'report_export',
  format: 'pdf'
})

// Track subscription changes
Rebutiq.track('subscription.upgraded', {
  from: 'starter',
  to: 'pro',
  mrr: 149
})

// Track refund policy viewed
Rebutiq.track('refund_policy.viewed', {
  duration: 12400  // ms spent on page
})

Param	Type	Required	Description
event	string	Yes	Event name using dot notation (e.g., `terms.accepted`, `feature.used`).
properties	object	No	Key-value pairs with additional context. All values must be serializable.

Recommended events to track for maximum dispute win rate:

Event	Type	Required	Why it matters
terms.accepted	string	High	Proves customer agreed to your refund policy before paying.
feature.used	string	High	Proves the customer received and used the service they paid for.
subscription.upgraded	string	Medium	Shows intentional purchasing behavior, countering fraud claims.
support.ticket.created	string	Medium	Shows whether customer attempted resolution before disputing.
invoice.viewed	string	Medium	Proves customer was aware of charges.

Rebutiq.policyViewed(options)

A convenience method for tracking when a user views your Terms of Service, refund policy, or cancellation policy. This creates a timestamped, IP-stamped record that is one of the strongest pieces of evidence in subscription-based disputes.

checkout.js

// Call when user views or accepts policy
Rebutiq.policyViewed({
  type: 'terms_of_service',
  version: 'v2.1',
  url: 'https://app.example.com/legal/terms',
  accepted: true
})

Param	Type	Required	Description
type	string	Yes	One of `terms_of_service`, `refund_policy`, or `cancellation_policy`.
version	string	Yes	Version identifier of the policy document.
url	string	No	URL where the policy is hosted. Included in evidence package.
accepted	boolean	No	Whether the user explicitly accepted (checkbox, button). Defaults to `false` (viewed only).

Rebutiq.page(properties)

Manually track a page view. This is only needed if you disabled autoTrack or you are using a single-page application with client-side routing that the SDK cannot detect automatically.

router.js

// For SPAs with client-side routing
router.afterEach((to) => {
  Rebutiq.page({
    path: to.path,
    title: to.meta.title,
    referrer: document.referrer
  })
})

NPM PACKAGE

React

The React package provides a RebutiqProvider context wrapper and hooks for tracking events declaratively. Install with npm or yarn, wrap your app, and use hooks anywhere in your component tree.

terminal

npm install @rebutiq/react

App.jsx

import { RebutiqProvider } from '@rebutiq/react'

function App() {
  return (
    <RebutiqProvider
      apiKey="rbq_proj_YOUR_KEY"
      autoTrack
      trackScrollDepth
    >
      <YourApp />
    </RebutiqProvider>
  )
}

Dashboard.jsx

import { useRebutiq, useIdentify } from '@rebutiq/react'

function Dashboard({ user }) {
  const { track, policyViewed } = useRebutiq()

  // Identify on mount
  useIdentify({
    userId: user.id,
    email: user.email,
    stripeCustomerId: user.stripeId
  })

  const handleExport = () => {
    track('feature.used', { feature: 'csv_export' })
    exportData()
  }

  return <button onClick={handleExport}>Export</button>
}

Vue

The Vue plugin registers Rebutiq globally and provides a composable for use in setup functions.

main.js

import { createApp } from 'vue'
import { RebutiqPlugin } from '@rebutiq/vue'

const app = createApp(App)

app.use(RebutiqPlugin, {
  apiKey: 'rbq_proj_YOUR_KEY',
  autoTrack: true,
  router: router  // auto-tracks route changes
})

app.mount('#app')

Profile.vue

<script setup>
import { useRebutiq } from '@rebutiq/vue'

const { track, identify } = useRebutiq()

identify({
  userId: user.value.id,
  email: user.value.email,
  stripeCustomerId: user.value.stripeId
})

function onSettingsSaved() {
  track('settings.updated', { section: 'profile' })
}
</script>

Node.js

The server-side SDK tracks backend events and provides Express middleware for automatic request logging. Use this for server-side actions like webhook processing, cron jobs, or API calls that the browser SDK cannot capture.

terminal

npm install @rebutiq/node

server.js

const express = require('express')
const { Rebutiq, rebutiqMiddleware } = require('@rebutiq/node')

const app = express()
const rbq = new Rebutiq({ apiKey: 'rbq_sk_YOUR_SECRET_KEY' })

// Auto-log all API requests with user context
app.use(rebutiqMiddleware(rbq, {
  getUserId: (req) => req.user?.id,
  excludePaths: ['/health', '/metrics']
}))

// Track server-side events explicitly
app.post('/api/invoices/:id/send', async (req, res) => {
  await sendInvoice(req.params.id)

  rbq.track({
    userId: req.user.id,
    event: 'invoice.sent',
    properties: {
      invoiceId: req.params.id,
      amount: 149.00,
      deliveryMethod: 'email'
    }
  })

  res.json({ success: true })
})

REST API

POST/v1/events

Send a custom event from any language or platform. All requests require your secret API key in the Authorization header. Events are processed in real-time and appear in the user's activity timeline within seconds.

cURL

curl -X POST https://api.rebutiq.com/v1/events \
  -H "Authorization: Bearer rbq_sk_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "usr_8f2k9d",
    "event": "feature.used",
    "properties": {
      "feature": "report_export",
      "format": "pdf",
      "fileSize": 24500
    },
    "timestamp": "2026-03-15T14:22:00Z",
    "context": {
      "ip": "102.89.45.12",
      "userAgent": "Mozilla/5.0..."
    }
  }'

Param	Type	Required	Description
userId	string	Yes	Your internal user identifier. Must match the ID used in `identify()`.
event	string	Yes	Event name. Use dot notation for namespacing.
properties	object	No	Arbitrary key-value pairs. Max 50 properties, 256 chars per value.
timestamp	string	No	ISO 8601 timestamp. Defaults to server receive time if omitted.
context.ip	string	No	Client IP address. Included in evidence for IP matching.
context.userAgent	string	No	Browser user agent string. Used for device fingerprinting.

Response: 201 Created with the event ID.

response.json
{
  "id": "evt_a1b2c3d4e5",
  "status": "accepted",
  "timestamp": "2026-03-15T14:22:00.123Z"
}

POST/v1/identify

Create or update a user profile from your backend. This is the server-side equivalent of Rebutiq.identify(). Use this when user data changes (plan upgrade, email update) or during server-side onboarding flows.

cURL

curl -X POST https://api.rebutiq.com/v1/identify \
  -H "Authorization: Bearer rbq_sk_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "usr_8f2k9d",
    "traits": {
      "email": "jane@acme.com",
      "name": "Jane Cooper",
      "stripeCustomerId": "cus_Qz8xfR4kL2m",
      "plan": "pro",
      "mrr": 149,
      "createdAt": "2026-01-15T09:22:00Z"
    }
  }'

Param	Type	Required	Description
userId	string	Yes	Your internal user identifier.
traits.email	string	Yes	User email. Used for Stripe customer matching.
traits.stripeCustomerId	string	Yes	Stripe customer ID. Required for dispute linking.
traits.name	string	No	Display name. Appears in evidence narratives.
traits.plan	string	No	Current subscription plan name.
traits.mrr	number	No	Monthly recurring revenue for this user.
traits.createdAt	string	No	ISO 8601 account creation date.

POST/v1/risk/check

Get a real-time risk score for a user. Returns a score from 0 to 100, where higher values indicate greater dispute likelihood. Use this to trigger proactive interventions — offer refunds, send retention emails, or flag accounts for manual review before a dispute is filed.

cURL

curl -X POST https://api.rebutiq.com/v1/risk/check \
  -H "Authorization: Bearer rbq_sk_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "userId": "usr_8f2k9d" }'

Response:

response.json
{
  "userId": "usr_8f2k9d",
  "riskScore": 73,
  "riskLevel": "high",
  "signals": [
    { "type": "activity_drop", "weight": 0.35, "detail": "No login in 14 days" },
    { "type": "cancel_page_visit", "weight": 0.25, "detail": "Visited /settings/cancel 3 times" },
    { "type": "rage_clicks", "weight": 0.15, "detail": "8 rage click events in last session" }
  ],
  "recommendation": "Consider proactive outreach or a retention offer",
  "checkedAt": "2026-03-15T14:22:00Z"
}

Param	Type	Required	Description
userId	string	Yes	The user to check. Must have been previously identified.

GET/v1/health

Check API availability and your current rate limit status. No authentication required.

cURL

curl https://api.rebutiq.com/v1/health

response.json
{
  "status": "operational",
  "version": "2.4.0",
  "latency": 12,
  "timestamp": "2026-04-04T10:00:00Z"
}

INTEGRATIONS

Stripe webhook setup

Rebutiq listens to Stripe webhooks to detect disputes the moment they are created. You can set this up in two ways: through our dashboard (recommended) or by manually adding our webhook endpoint in Stripe.

Option A: Dashboard setup (recommended)

Go to Dashboard > Settings > Integrations > Stripe and click "Connect Stripe account." This uses Stripe Connect OAuth and automatically configures the webhook with the correct events.

Option B: Manual webhook

If you prefer manual setup, add the following webhook endpoint in your Stripe Dashboard under Developers > Webhooks:

Webhook URL

https://api.rebutiq.com/webhooks/stripe

Subscribe to these events:

Required events
charge.dispute.created        # Triggers evidence collection + auto-submit
charge.dispute.updated        # Tracks dispute status changes
charge.dispute.closed         # Records win/loss outcome
customer.subscription.created # Logs subscription start for evidence
customer.subscription.updated # Tracks plan changes
customer.subscription.deleted # Records cancellations
invoice.payment_succeeded     # Logs successful charges
invoice.payment_failed        # Tracks failed payment attempts

After adding the endpoint, copy the webhook signing secret from Stripe and paste it in Dashboard > Settings > Integrations > Stripe > Webhook secret. Rebutiq verifies every webhook signature to prevent spoofing.

Evidence templates

Rebutiq includes 7 pre-built evidence templates, one for each Stripe dispute reason code. Each template maps to the exact fields Stripe expects and is compliant with Visa Compelling Evidence 3.0 requirements.

Reason code	Type	Required	Key evidence fields
fraudulent	template	Auto	IP match, device fingerprint, activity log, prior transactions from same card
subscription_canceled	template	Auto	Cancellation policy, no cancel request received, continued usage after charge
product_not_received	template	Auto	Access logs, feature usage timestamps, delivery confirmation (digital)
product_unacceptable	template	Auto	Feature usage history, no support tickets filed, service uptime logs
unrecognized	template	Auto	Receipt delivery proof, billing descriptor match, login from same IP
duplicate	template	Auto	Unique invoice IDs, separate service periods, distinct line items
general	template	Auto	Full activity timeline, TOS acceptance, communication history

Templates are selected automatically based on the dispute reason code. You can customize templates or create new ones in Dashboard > Settings > Evidence templates.

Auto-refund API

The auto-refund engine (available on Pro and Scale plans) automatically refunds high-risk charges before they become disputes. This prevents the $15 Stripe dispute fee and protects your dispute rate from crossing Visa/Mastercard thresholds.

cURL

# Configure auto-refund rules
curl -X POST https://api.rebutiq.com/v1/auto-refund/rules \
  -H "Authorization: Bearer rbq_sk_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "riskThreshold": 85,
    "maxRefundAmount": 500,
    "cooldownDays": 7,
    "excludePlans": ["enterprise"],
    "notifyEmail": "billing@yourapp.com",
    "requireApproval": false
  }'

Param	Type	Required	Description
enabled	boolean	Yes	Enable or disable auto-refund globally.
riskThreshold	number	Yes	Minimum risk score (0-100) to trigger a refund. Recommended: 85+.
maxRefundAmount	number	No	Maximum charge amount (USD) eligible for auto-refund. Defaults to no limit.
cooldownDays	number	No	Minimum days after charge before auto-refund triggers. Defaults to 3.
excludePlans	array	No	Plan names to exclude from auto-refund.
notifyEmail	string	No	Email to notify when an auto-refund is triggered.
requireApproval	boolean	No	If true, sends an approval request instead of refunding automatically.

When a charge meets the threshold, Rebutiq issues a full refund via the Stripe API, logs the event, and sends a notification. The refund reason is set to requested_by_customer to keep your Stripe account in good standing.