Subscription Types

SubscriptionProperties

Comprehensive subscription data for tracking user subscription lifecycle.

export interface SubscriptionProperties {
  // Status & Plan
  status: "active" | "trialing" | "past_due" | "canceled" | "paused" | "incomplete" | "incomplete_expired" | "unpaid";
  plan_id?: string;
  plan_name?: string;
  plan_tier?: string;

  // Pricing (in cents)
  mrr?: number;
  arr?: number;
  ltv?: number;
  currency?: string;

  // Billing Cycle
  billing_interval?: "day" | "week" | "month" | "year";
  billing_cycle_anchor?: string;
  current_period_start?: string;
  current_period_end?: string;

  // Trial
  trial_start?: string;
  trial_end?: string;
  is_trial?: boolean;

  // Payment (PCI-safe - last 4 digits only)
  payment_method_type?: string;
  payment_method_last4?: string;
  payment_method_brand?: string;

  // Cancellation
  cancel_at_period_end?: boolean;
  canceled_at?: string;
  cancellation_reason?: string;

  // Provider Info
  provider?: "stripe" | "paddle" | "chargebee" | "manual" | string;
  provider_customer_id?: string;
  provider_subscription_id?: string;

  // Metadata
  created_at?: string;
  updated_at?: string;

  // Custom fields
  [key: string]: string | number | boolean | null | undefined;
}

Status & Plan Properties

string

required

Current subscription status. Possible values:

active: Subscription is active and paid
trialing: In trial period
past_due: Payment failed but subscription still active
canceled: Subscription has been canceled
paused: Subscription is temporarily paused
incomplete: Initial payment pending
incomplete_expired: Initial payment failed
unpaid: Subscription unpaid and inactive

string

Unique identifier for the subscription plan.

string

Human-readable name of the subscription plan.

string

Tier level of the plan (e.g., “free”, “starter”, “pro”, “enterprise”).

Pricing Properties

number

Monthly Recurring Revenue in cents.

number

Annual Recurring Revenue in cents.

number

Customer Lifetime Value in cents.

string

Currency code (e.g., “usd”, “eur”, “gbp”).

Billing Cycle Properties

string

Billing frequency. Possible values: day, week, month, year.

string

ISO 8601 date string for when the billing cycle is anchored.

string

ISO 8601 date string for the start of the current billing period.

string

ISO 8601 date string for the end of the current billing period.

Trial Properties

string

ISO 8601 date string for when the trial period started.

string

ISO 8601 date string for when the trial period ends.

boolean

Whether the subscription is currently in a trial period.

Payment Properties

string

Type of payment method (e.g., “card”, “bank_account”, “paypal”). PCI-compliant - no sensitive data stored.

string

Last 4 digits of the payment method (PCI-safe).

string

Brand of the payment method (e.g., “visa”, “mastercard”, “amex”).

Cancellation Properties

boolean

Whether the subscription will cancel at the end of the current period.

string

ISO 8601 date string for when the subscription was canceled.

string

Reason provided for cancellation.

Provider Properties

string

Payment provider name. Common values: stripe, paddle, chargebee, manual, or custom provider name.

string

Customer ID in the payment provider’s system.

string

Subscription ID in the payment provider’s system.

Metadata Properties

string

ISO 8601 date string for when the subscription was created.

string

ISO 8601 date string for when the subscription was last updated.

string | number | boolean | null | undefined

Additional custom fields for provider-specific or custom subscription data.

ChurnRiskMetrics

Predictive analytics for customer churn risk assessment.

export interface ChurnRiskMetrics {
  risk_score: number;
  risk_category: "low" | "medium" | "high" | "critical";
  factors: {
    engagement_score?: number;
    days_since_last_active?: number;
    feature_adoption_rate?: number;
    support_tickets?: number;
    negative_feedback_count?: number;
    payment_failures?: number;
  };
  predicted_churn_date?: string;
  intervention_recommended?: boolean;
}

Properties

number

required

Churn risk score from 0-100, where higher values indicate greater risk.

string

required

Risk category classification. Possible values: low, medium, high, critical.

object

required

Contributing factors to the churn risk score:

engagement_score (number): User engagement score (0-100)
days_since_last_active (number): Days since user was last active
feature_adoption_rate (number): Percentage of features adopted (0-100)
support_tickets (number): Number of support tickets filed
negative_feedback_count (number): Count of negative feedback submissions
payment_failures (number): Number of failed payment attempts

string

ISO 8601 date string for the predicted churn date.

boolean

Whether intervention is recommended to prevent churn.

Experiment

A/B test experiment configuration.

export interface Experiment {
  id: string;
  name: string;
  description?: string;
  key: string;
  status: "DRAFT" | "RUNNING" | "PAUSED" | "COMPLETED" | "ARCHIVED";
  trafficSplit: number;
  startDate?: string;
  endDate?: string;
  createdAt: string;
  updatedAt: string;
  variants: Variant[];
}

Properties

string

required

Unique identifier for the experiment.

string

required

Human-readable name of the experiment.

string

Detailed description of the experiment’s purpose.

string

required

Unique key used to reference the experiment in code.

string

required

Current status of the experiment. Possible values: DRAFT, RUNNING, PAUSED, COMPLETED, ARCHIVED.

number

required

Percentage of traffic allocated to this experiment (0-100).

string

ISO 8601 date string for when the experiment starts.

string

ISO 8601 date string for when the experiment ends.

string

required

ISO 8601 date string for when the experiment was created.

string

required

ISO 8601 date string for when the experiment was last updated.

Variant[]

required

Array of variants in this experiment.

Variant

A variant within an A/B test experiment.

export interface Variant {
  id: string;
  name: string;
  key: string;
  description?: string;
  isControl: boolean;
  trafficSplit: number;
  createdAt: string;
  updatedAt: string;
}

Properties

string

required

Unique identifier for the variant.

string

required

Human-readable name of the variant.

string

required

Unique key used to reference the variant in code.

string

Description of what this variant represents.

boolean

required

Whether this variant is the control group.

number

required

Percentage of traffic allocated to this variant (0-100).

string

required

ISO 8601 date string for when the variant was created.

string

required

ISO 8601 date string for when the variant was last updated.

ExperimentAssignment

User’s assignment to an experiment variant.

export interface ExperimentAssignment {
  experimentId: string;
  variantId: string;
  variantKey: string;
  variantName: string;
  isControl: boolean;
  assignedAt: string;
  experiment?: Experiment;
}

Properties

string

required

ID of the experiment the user is assigned to.

string

required

ID of the assigned variant.

string

required

Key of the assigned variant.

string

required

Name of the assigned variant.

boolean

required

Whether the assigned variant is the control group.

string

required

ISO 8601 date string for when the assignment was made.

Experiment

Full experiment details (optional).

Core API

Hooks

Components

Types

SubscriptionProperties

Status & Plan Properties

Pricing Properties

Billing Cycle Properties

Trial Properties

Payment Properties

Cancellation Properties

Provider Properties

Metadata Properties

ChurnRiskMetrics

Properties

Experiment

Properties

Variant

Properties

ExperimentAssignment

Properties

​SubscriptionProperties

​Status & Plan Properties

​Pricing Properties

​Billing Cycle Properties

​Trial Properties

​Payment Properties

​Cancellation Properties

​Provider Properties

​Metadata Properties

​ChurnRiskMetrics

​Properties

​Experiment

​Properties

​Variant

​Properties

​ExperimentAssignment

​Properties

SubscriptionProperties

Status & Plan Properties

Pricing Properties

Billing Cycle Properties

Trial Properties

Payment Properties

Cancellation Properties

Provider Properties

Metadata Properties

ChurnRiskMetrics

Properties

Experiment

Properties

Variant

Properties

ExperimentAssignment

Properties