Revenue Data Structures

type EventType = "purchase" | "subscription_purchase" | "trial_conversion" | "renewal" | "refund" | "cancellation" | "expiration" | "trial_start";

interface PaginatedRevenue {
  /** Array of revenue events */
  items: RevenueEvent[];
  /** Current page number (1-indexed) */
  page: number;
  /** Number of items per page */
  limit: number;
  /** Total number of items across all pages */
  total: number;
  /** Total number of pages */
  totalPages: number;
  /** Whether there is a next page */
  hasNext: boolean;
  /** Whether there is a previous page */
  hasPrev: boolean;
  /** Revenue summary statistics for the current period */
  summary: RevenueSummary;
  /** Revenue summary statistics for the previous period (only present if prevSince/prevUntil were provided in the request) */
  previousSummary: unknown;
  /** Time series data (only included if includeSeries=true) */
  series?: RevenueSeriesBucket[];
}

interface RevenueEvent {
  /** Unique event identifier */
  id: string;
  /** Workspace identifier */
  workspaceId: string;
  /** Integration identifier if event came from an integration */
  integrationId?: string;
  eventType: EventType;
  /** Transaction amount in cents */
  amountCents: number;
  /** Currency code (ISO 4217) */
  currency: string;
  /** External transaction ID from the provider */
  externalId?: string;
  /** Additional metadata associated with the event */
  metadata?: object;
  /** ISO 8601 timestamp when the event occurred */
  occurredAt: string;
  /** ISO 8601 timestamp when the event was recorded */
  createdAt: string;
  provider?: IntegrationProvider;
}

interface RevenueSeriesBucket {
  /** ISO 8601 timestamp for the start of the time bucket */
  bucketTs: string;
  /** Original currency for this bucket (before conversion) */
  currency: string;
  /** Total positive revenue in cents (purchases + subscriptions + renewals) */
  revenueCents: number;
  /** One-time purchase revenue in cents */
  purchasesCents: number;
  /** Subscription renewal revenue in cents */
  renewalsCents: number;
  /** Trial conversion revenue in cents */
  trialsCents: number;
  /** Refund amount in cents */
  refundsCents: number;
  /** New subscription revenue in cents (optional) */
  newSubsCents?: number;
  /** Number of purchases in this bucket */
  purchaseCount: number;
  /** Number of renewals in this bucket */
  renewalCount: number;
  /** Number of trial conversions in this bucket */
  trialCount: number;
  /** Number of trial starts in this bucket */
  trialStartCount: number;
  /** Number of refunds in this bucket */
  refundCount: number;
  /** Number of new subscriptions in this bucket (optional) */
  newSubsCount?: number;
}

interface RevenueSummary {
  /** Base currency for all amounts (converted to this currency) */
  currency: string;
  /** Total gross revenue in cents (before refunds) */
  grossRevenueCents: number;
  /** Total net revenue in cents (after refunds) */
  netRevenueCents: number;
  /** Total refunds in cents */
  refundCents: number;
  /** Total recurring revenue (subscriptions + renewals) in cents */
  recurringNetCents: number;
  /** Number of one-time purchases */
  purchaseCount: number;
  /** Number of subscription purchases */
  subscriptionPurchaseCount: number;
  /** Number of subscription renewals */
  renewalCount: number;
  /** Number of refunds */
  refundCount: number;
  /** Number of cancellations */
  cancellationCount: number;
  /** Total number of positive charge events */
  positiveChargeCount: number;
  /** Number of trial starts */
  trialCount: number;
  /** Number of trial conversions */
  trialConversionCount: number;
  /** Trial conversion rate as a decimal (0-1). Formula: trialConversionCount / trialCount */
  trialConversionRate: number;
  /** Cancellation rate as a decimal (0-1). Formula: cancellationCount / (renewalCount + subscriptionPurchaseCount) */
  cancellationRate: number;
  /** Refund rate as a decimal (0-1). Formula: refundCents / grossRevenueCents */
  refundRate: number;
  /** Monthly Run Rate in cents. Formula: (netRevenueCents / spanDays) * 30 */
  mrrCents: number;
  /** Average order value in cents. Formula: netRevenueCents / positiveChargeCount */
  averageOrderValueCents: number;
  /** Count of unique subscriptions that were cancelled. Uses subscription_id (Stripe) or original_transaction_id (RevenueCat/Superwall) to deduplicate. */
  uniqueCancelledSubs: number;
  /** Count of unique subscriptions with any subscription-related activity (renewals, purchases, trial conversions, or cancellations). Used as denominator for cancellation rate. Uses subscription_id (Stripe) or original_transaction_id (RevenueCat/Superwall) to deduplicate. */
  uniqueActiveSubs: number;
}

type IntegrationProvider = "revenuecat" | "stripe" | "app_store_connect" | "shopify" | "google_play_console" | "whop" | "paddle" | "woocommerce" | "superwall";