Product Analytics

Understand your Product Analytics

The Product Analytics API provides comprehensive insights into individual product performance through detailed analytics tracking and conversion metrics for your marketing campaigns.

What is Product Analytics? Copied

The Product Analytics API is like having a dedicated performance monitor for each product in your catalog. It gives you deep insights into how specific products perform across different campaigns, tracking everything from insider engagement to conversion rates and revenue generation at the product level.

Why is Product Analytics useful? Copied

Product analytics bridges individual product data with campaign performance, helping businesses optimize their product mix and marketing strategies through data-driven product insights.

• Marketing Teams: Identify top-performing products and optimize campaign allocation based on product-specific conversion rates and revenue metrics.

• Product Teams: Understand which products resonate most with different insider segments and optimize product positioning accordingly.

• Finance Teams: Track revenue attribution at the product level and calculate true product ROI across all marketing channels.

The API works continuously in the background, capturing every product interaction and linking them to purchases, campaigns, and insider performance.

How does it work? Copied

The API provides comprehensive product-level insights by aggregating all instances and interactions related to specific products. You can track everything from basic engagement metrics to detailed conversion funnels and revenue attribution for individual products.

• What It Tracks: Product-specific instances, conversion rates, revenue attribution, campaign effectiveness, and insider engagement patterns for each product.

• Example: See that Product A generated 284 instances with 89 purchases (31% conversion rate) and $6,254 total revenue across 3 campaigns this week.

• Access Patterns: Time-based aggregation for trend analysis, purchase filtering for conversion optimization, and campaign attribution for performance evaluation.

Error Responses Copied

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

Authentication & Authorization Errors Copied

401 Unauthorized

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

403 Forbidden

{
  "success": false,
  "error": "Forbidden",
  "message": "Insufficient permissions to access this product.",
  "details": "string",
  "meta": {
    "timestamp": "ISO 8601 timestamp",
    "requestId": "UUID"
  }
}

Client Errors Copied

400 Bad Request

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

404 Not Found

{
  "success": false,
  "error": "Not Found",
  "message": "Product not found with the specified product_id",
  "meta": {
    "timestamp": "ISO 8601 timestamp",
    "requestId": "UUID"
  }
}

409 Conflict

{
  "success": false,
  "error": "Conflict",
  "message": "Request conflicts with current product state.",
  "details": "string",
  "meta": {
    "timestamp": "ISO 8601 timestamp",
    "requestId": "UUID"
  }
}

422 Unprocessable Entity

{
  "success": false,
  "error": "Validation Error",
  "message": "Request validation failed.",
  "details": "string",
  "validation_errors": [
    {
      "field": "string",
      "message": "string",
      "code": "string"
    }
  ],
  "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 Copied

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"
  }
}

502 Bad Gateway

{
  "success": false,
  "error": "Bad Gateway",
  "message": "Upstream service unavailable.",
  "details": "string",
  "meta": {
    "timestamp": "ISO 8601 timestamp",
    "requestId": "UUID"
  }
}

503 Service Unavailable

{
  "success": false,
  "error": "Service Unavailable",
  "message": "Service temporarily unavailable. Please retry later.",
  "details": "string",
  "retry_after": "number (seconds)",
  "meta": {
    "timestamp": "ISO 8601 timestamp",
    "requestId": "UUID"
  }
}

504 Gateway Timeout

{
  "success": false,
  "error": "Gateway Timeout",
  "message": "Request timeout. Please try again.",
  "details": "string",
  "meta": {
    "timestamp": "ISO 8601 timestamp",
    "requestId": "UUID"
  }
}

API Endpoints Copied

Product Analytics Copied

Get Product Analytics

GET /api/partner/v1/products/{product_id}/analytics
GET /api/partner/v1/products/{product_id}/analytics?time_frame=per_day&limit=20&is_purchase=true

Retrieve aggregated product performance metrics and analytics data with comprehensive insights into product effectiveness, insider engagement, and conversion tracking across specified time periods.

Parameters:

• time_frame (required): Time aggregation period: per_hour, per_day, per_month, custom_range

• start_date (conditional): Start date for analysis (required for custom_range). Format: YYYY-MM-DD

• end_date (conditional): End date for analysis (required for custom_range). Format: YYYY-MM-DD

• is_purchase (optional): Filter by purchase events: true, false, all (default: all)

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

• limit (optional): Results per page, max 100 (default: 50)

Success Response (200 OK):

{
  "success": "boolean",
  "message": "string",
  "data": {
    "product_id": "UUID",
    "time_frame": "string",
    "instances": [
      {
        "instance_id": "UUID",
        "campaign_id": "UUID",
        "insider_id": "UUID",
        "is_purchase": "boolean",
        "purchased_insider_id": "UUID or null",
        "timestamp": "ISO 8601 timestamp",
        "revenue": "number"
      }
    ],
    "summary": {
      "total_instances": "number",
      "purchase_instances": "number", 
      "non_purchase_instances": "number",
      "total_revenue": "number",
      "conversion_rate": "number (0.0-1.0)"
    }
  },
  "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 UUID format for product_id

• 400: Invalid time_frame parameter (must be per_hour, per_day, per_month, or custom_range)

• 400: Missing start_date for custom_range

• 400: Missing end_date for custom_range

• 400: Invalid date format (must be YYYY-MM-DD)

• 400: End date must be after start_date

• 400: Date range too large (exceeds maximum allowed period)

• 400: Invalid is_purchase parameter (must be true, false, or all)

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

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

• 404: Product not found with the specified product_id

• 403: Insufficient permissions to view product analytics

• 422: No analytics data available for the specified time period

Product Analytics Features Copied

Time Frame Options Copied

• per_hour - Aggregates product analytics data by hour for detailed temporal analysis

• per_day - Aggregates product analytics data by day (most common) for daily trend monitoring

• per_month - Aggregates product analytics data by month for long-term trend analysis

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

Purchase Status Filtering Copied

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

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

• all - All instances regardless of purchase status (complete overview)

Analytics Rate Limiting Copied

• Product Analytics: 200 requests per hour per partner

• Bulk queries: Optimized for large datasets with efficient pagination

Data Structures Copied

Product Analytics Instance Copied

{
  instance_id: string;         // UUID v4 format
  campaign_id: string;         // UUID v4 format
  insider_id: string;          // UUID v4 format
  is_purchase: boolean;        // Whether instance resulted in purchase
  purchased_insider_id: string | null; // UUID v4 format, null if no purchase
  timestamp: string;           // ISO 8601 format - instance occurrence time
  revenue: number;             // Revenue generated from this instance
}

Product Analytics Summary Copied

{
  total_instances: number;     // Total number of product instances
  purchase_instances: number;  // Number of instances that resulted in purchases
  non_purchase_instances: number; // Number of instances without purchases
  total_revenue: number;       // Total revenue generated by this product
  conversion_rate: number;     // Percentage of instances that resulted in purchases (0.0-1.0)
}

Product Analytics Response Copied

{
  product_id: string;          // UUID v4 format
  time_frame: string;          // Selected time aggregation period
  instances: ProductInstance[]; // Array of product instances
  summary: ProductSummary;     // Aggregated metrics for the product
}

Product Performance Insights Copied

Conversion Tracking Copied

Track how effectively each product converts across different campaigns and time periods. The conversion rate metric helps identify top-performing products and optimization opportunities.

Revenue Attribution Copied

Monitor exact revenue contribution from each product, enabling precise ROI calculations and budget allocation decisions based on actual product performance.

Campaign Effectiveness Copied

Analyze how different campaigns perform for specific products, helping optimize campaign-product combinations for maximum effectiveness.

Insider Engagement Copied

Understand which products resonate most with different insider segments and optimize product positioning accordingly.

Security Features Copied

Product-Level Access Control Copied

• All product analytics data is scoped to your partner account

• Secret key authentication provides automatic data filtering

• No access to other partners' product data

Data Privacy Copied

• Product analytics respect user privacy settings

• GDPR-compliant data handling and retention

• Anonymized analytics where required by regulations

Rate Limiting Copied

• Fair usage policies applied per partner

• Generous limits for product analytics queries

• Automatic rate limit headers in responsesHow Product Analytics Works

Product analytics automatically captures and aggregates all interactions related to specific products through your authenticated API access. When users engage with your products through tracked campaigns, our system seamlessly attributes these interactions to create comprehensive product performance profiles.

• Automatic Product Tracking: All product-related interactions are automatically captured and attributed to the correct product.

• Real-time Aggregation: Product metrics are updated in real-time as new instances and purchases occur.

• Example: Product A receives 284 interactions across 3 campaigns, with 89 purchases generating $6,254 revenue and achieving a 31.3% conversion rate - all automatically calculated and available via the API.