Cashin DocsGuideCashin Partner APIs

Instance Analytics

Understand your Insider’s Instance Analytics

The Instance Analytics API provides comprehensive insights into user interaction journeys and purchase behaviors through detailed event tracking and analytics data for your marketing campaigns.

What is are Instance Analytics?

The Instance Analytics API is like having a complete customer journey recorder for your marketing campaigns. It captures every user interaction from their first page view to final purchase, giving you detailed insights into conversion paths, event sequences, and reward distributions across your entire funnel.

Why is Instance Analytics useful?

Instance analytics bridges individual user actions with business outcomes, helping you understand the complete customer journey and optimize every touchpoint for maximum conversion.

  • Marketing Teams: Track complete conversion funnels and identify which interaction sequences lead to purchases, then optimize campaigns based on successful patterns.

  • Finance Teams: Monitor reward distributions, discount usage, and revenue attribution across all instances for accurate ROI calculations.

  • Product Teams: Analyze user behavior patterns and event sequences to optimize checkout flows and user experience design.

The API works continuously in the background, capturing every tracked interaction and linking them to purchases, rewards, and campaign performance.

How does it work?

The API provides two complementary views of your data: summary analytics for trend monitoring and detailed instance breakdowns for deep-dive analysis. You can track everything from high-level conversion metrics to granular event sequences within individual user sessions.

  • What It Tracks: Complete user journeys, event sequences, purchase outcomes, reward distributions, and campaign attribution across all your instances.

  • Example: See that Instance #479 included 4 events (page view → scroll → add to cart → purchase) resulting in $29.99 revenue and $14.99 insider rewards.

  • Access Patterns: List analytics for overview monitoring, detailed instance analysis for conversion optimization, and bulk queries for data exports.

Team

Benefit

Example

Marketing

Journey optimization

"Instances with scroll events have 34% higher conversion rates than page-view only"

Finance

Revenue tracking

"Track $1,247 in rewards distributed across 87 successful instances this week"

Product

UX insights

"Users who spend 4+ minutes on product pages convert 67% more often"

Authentication

All API requests require authentication using a secret key in the Authorization header.

Header Format 

Authorization: Bearer sk_live_abc123def456...

Authentication Description

  • All API requests require a secret key

  • Single key system (no public/private key separation)

  • Keys follow format: sk_live_ or sk_test_ + 32 character string

Standard Response Format

Success Response Template 

{
  "success": "boolean",
  "message": "string",
  "data": "array[]",
  "meta": {
    "timestamp": "ISO 8601 timestamp",
    "requestId": "UUID"
  }
}

Error Response Template 

{
  "success": false,
  "error": "string",
  "message": "string",
  "fields": [
    {
      "field": "string",
      "message": "string",
      "code": "string"
    }
  ],
  "meta": {
    "timestamp": "ISO 8601 timestamp",
    "requestId": "UUID"
  }
}

Error Responses

All endpoints can return the following HTTP status codes and error responses:

Authentication & Authorization Errors

401 Unauthorized

{
  "success": false,
  "error": "Unauthorized",
  "message": "Invalid or missing secret key",
  "meta": {
    "timestamp": "ISO 8601 timestamp",
    "requestId": "UUID"
  }
}

Client Errors

400 Bad Request

{
  "success": false,
  "error": "Bad Request",
  "message": "Validation failed for N fields",
  "fields": [
    {
      "field": "string",
      "message": "string",
      "code": "string"
    }
  ],
  "meta": {
    "timestamp": "ISO 8601 timestamp",
    "requestId": "UUID"
  }
}

404 Not Found

{
  "success": false,
  "error": "Not Found",
  "message": "One or more instance IDs not found",
  "meta": {
    "timestamp": "ISO 8601 timestamp",
    "requestId": "UUID"
  }
}

429 Too Many Requests

{
  "success": false,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please try again later",
  "meta": {
    "timestamp": "ISO 8601 timestamp",
    "requestId": "UUID"
  }
}

Server Errors

500 Internal Server Error

{
  "success": false,
  "error": "Internal Server Error",
  "message": "An unexpected error occurred. Please try again later",
  "meta": {
    "timestamp": "ISO 8601 timestamp",
    "requestId": "UUID"
  }
}

API Endpoints

List Instance Analytics

Get Instance Analytics Summary

GET /partner/v1/instances/analytics
GET /partner/v1/instances/analytics?is_purchased=true&time_frame=day&page=1&limit=20

Retrieves a paginated list of instance analytics data with optional filtering by purchase status and time frame grouping.

Parameters:

  • is_purchased (optional): Filter instances by purchase status (true/false)

  • time_frame (optional): Time grouping: hour, day, custom (default: day)

  • start_date (conditional): ISO 8601 date. Required when time_frame is custom

  • end_date (conditional): ISO 8601 date. Required when time_frame is custom

  • page (optional): Page number for pagination (default: 1)

  • limit (optional): Number of records per page (default: 20, max: 100)

Success Response (200 OK):

{
  "success": "boolean",
  "time_frame": "string",
  "message": "string",
  "data": [
    {
      "timestamp": "ISO 8601 timestamp",
      "instance_id": "UUID",
      "is_purchase": "boolean",
      "insider_id": "UUID",
      "purchased_insider_id": "UUID or null"
    }
  ],
  "pagination": {
    "page": "number",
    "limit": "number", 
    "total": "number",
    "totalPages": "number",
    "hasNext": "boolean",
    "hasPrevious": "boolean"
  },
  "meta": {
    "timestamp": "ISO 8601 timestamp",
    "requestId": "UUID"
  }
}

Specific Error Cases:

  • 400: Invalid time_frame parameter (must be hour, day, or custom)

  • 400: Missing start_date for custom time_frame

  • 400: Missing end_date for custom time_frame

  • 400: end_date must be after start_date

  • 400: Invalid page number (must be positive integer)

  • 400: Invalid limit value (must be 1-100)

  • 400: Invalid is_purchased parameter (must be boolean)

Get Instance Analytics Details

Get Detailed Instance Data

POST /partner/v1/instances/analytics
POST /partner/v1/instances/analytics?events=first

Retrieves detailed analytics data for specific instances including events, orders, and rewards with granular event filtering options.

Parameters:

  • events (optional): Event filtering: first, last, all (default: all)

Request Body:

{
  "instance_ids": ["UUID"]
}

Success Response (200 OK):

{
  "success": "boolean",
  "message": "string",
  "data": [
    {
      "instance_id": "UUID",
      "insider_id": "UUID",
      "purchased_insider_id": "UUID or null",
      "campaign_id": "UUID",
      "is_purchase": "boolean",
      "events": [
        {
          "id": "UUID",
          "name": "string",
          "tracker_type": "string",
          "reference_id": "string or undefined",
          "created_at": "ISO 8601 timestamp",
          "updated_at": "ISO 8601 timestamp",
          "metadata": "object"
        }
      ],
      "order": {
        "id": "UUID",
        "total": "number",
        "currency": "string",
        "status": "string",
        "items": [
          {
            "product_id": "string",
            "quantity": "number",
            "price": "number"
          }
        ],
        "created_at": "ISO 8601 timestamp"
      },
      "insider_rewards": [
        {
          "id": "UUID",
          "insider_id": "UUID",
          "type": "string",
          "amount": "number",
          "currency": "string",
          "status": "string",
          "created_at": "ISO 8601 timestamp"
        }
      ],
      "order_discounted_price": "number or null",
      "cashfunds_use": "number",
      "credits_used": "number"
    }
  ],
  "meta": {
    "timestamp": "ISO 8601 timestamp",
    "requestId": "UUID"
  }
}

Event Metadata by Tracker Type:

Page View Events:

{
  "url": "string",
  "user_agent": "string"
}

Click Tracking Events:

{
  "product_id": "string",
  "price": "number"
}

Scroll Tracking Events:

{
  "scroll_depth": "number",
  "max_scroll": "number",
  "page_height": "number",
  "viewport_height": "number",
  "scroll_speed": "string"
}

Time Tracking Events:

{
  "time_spent": "number (seconds)",
  "active_time": "number (seconds)",
  "idle_time": "number (seconds)",
  "session_duration": "number (seconds)",
  "engagement_score": "number (0.0-1.0)"
}

Specific Error Cases:

  • 400: Invalid events parameter (must be first, last, or all)

  • 400: Missing instance_ids in request body

  • 400: Must provide at least 1 instance ID

  • 400: Maximum 50 instance IDs per request

  • 400: Invalid UUID format for instance IDs

  • 404: One or more instance IDs not found

Instance Analytics Features

Time Frame Options

  • hour - Groups analytics data by hour for detailed temporal analysis

  • day - Groups analytics data by day (default) for daily trend monitoring

  • custom - Requires start_date and end_date parameters for flexible date ranges

Event Filtering

  • first - Returns only the first event for each instance (useful for entry point analysis)

  • last - Returns only the last event for each instance (useful for exit point analysis)

  • all - Returns all events for each instance in chronological order (default)

Purchase Status Filtering

  • true - Only instances that resulted in purchases (conversion analysis)

  • false - Only instances that did not result in purchases (abandonment analysis)

  • null/undefined - All instances regardless of purchase status (complete overview)

Analytics Rate Limiting

  • List Analytics: 100 requests per hour per partner

  • Get Details: 50 requests per hour per partner

  • Bulk Details: Limited to 50 instance IDs per request

Data Structures

Instance Analytics List Item 

{
  timestamp: string;           // ISO 8601 format - instance session time
  instance_id: string;         // UUID v4 format
  is_purchase: boolean;        // Whether instance resulted in purchase
  insider_id: string;          // UUID v4 format
  purchased_insider_id: string | null; // UUID v4 format, null if no purchase
}

Instance Analytics Details 

{
  instance_id: string;         // UUID v4 format
  insider_id: string;          // UUID v4 format  
  purchased_insider_id: string | null; // UUID v4 format, null if no purchase
  campaign_id: string;         // UUID v4 format
  is_purchase: boolean;        // Whether instance resulted in purchase
  events: Event[];             // Array of events in chronological order
  order: Order | null;         // Order details if purchase occurred
  insider_rewards: InsiderReward[]; // Array of rewards earned
  order_discounted_price: number | null; // Total after discount applied
  cashfunds_use: number;       // Cashfunds amount used
  credits_used: number;        // Credits amount used
}

Event Structure 

{
  id: string;                  // UUID v4 format
  name: string;                // Event name
  tracker_type: TrackerType;   // Type of tracking event
  reference_id?: string;       // Optional reference identifier
  created_at: string;          // ISO 8601 format
  updated_at: string;          // ISO 8601 format
  metadata: object;            // Additional event data (varies by tracker type)
}

Insider Reward Structure 

{
  id: string;                  // UUID v4 format
  insider_id: string;          // UUID v4 format
  type: string;                // Reward type (e.g., "commission")
  amount: number;              // Reward amount
  currency: string;            // Currency code (e.g., "USD")
  status: string;              // Reward status (e.g., "pending", "paid")
  created_at: string;          // ISO 8601 format
}

Tracker Types

  • page_view - Page view tracking events for navigation analysis

  • click_tracking - Click interaction events for engagement measurement

  • scroll_tracking - Scroll behavior events for content engagement analysis

  • time_tracking - Time-based engagement events for session analysis

Security Features

Partner Isolation

  • All analytics data is isolated by partner account

  • Secret keys provide automatic data filtering

  • No cross-partner data access possible

Data Privacy

  • Personal data is anonymized in analytics responses

  • GDPR compliance features included

  • Data retention policies enforced automatically

  • Audit logging for all access requests

Rate Limiting

  • Implemented per partner per endpoint

  • Sliding window algorithm for fair usage

  • Automatic rate limit headers included in responses

  • Graceful degradation when limits exceeded

Key Differences Between Endpoints

List Analytics Endpoint

Perfect for monitoring overall trends and identifying patterns across your instances. Each response row represents one instance with basic attribution data. Use this for dashboards, conversion rate monitoring, and identifying time-based patterns in user behavior.

Details Analytics Endpoint

Ideal for deep-dive analysis of specific user journeys. Each response includes the complete event sequence, purchase details, and reward information for selected instances. Use this for conversion funnel optimization, user journey analysis, and detailed attribution modelling.

© 2025 Cashin Labs Inc. All rights reserved.