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

status

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

plan_id

string

Unique identifier for the subscription plan.

plan_name

string

Human-readable name of the subscription plan.

plan_tier

string

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

Pricing Properties

mrr

number

Monthly Recurring Revenue in cents.

arr

number

Annual Recurring Revenue in cents.

ltv

number

Customer Lifetime Value in cents.

currency

string

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

Billing Cycle Properties

billing_interval

string

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

billing_cycle_anchor

string

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

current_period_start

string

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

current_period_end

string

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

Trial Properties

trial_start

string

ISO 8601 date string for when the trial period started.

trial_end

string

ISO 8601 date string for when the trial period ends.

is_trial

boolean

Whether the subscription is currently in a trial period.

Payment Properties

payment_method_type

string

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

payment_method_last4

string

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

payment_method_brand

string

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

Cancellation Properties

cancel_at_period_end

boolean

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

canceled_at

string

ISO 8601 date string for when the subscription was canceled.

cancellation_reason

string

Reason provided for cancellation.

Provider Properties

provider

string

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

provider_customer_id

string

Customer ID in the payment provider’s system.

provider_subscription_id

string

Subscription ID in the payment provider’s system.

Metadata Properties

created_at

string

ISO 8601 date string for when the subscription was created.

updated_at

string

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

[key: string]

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

risk_score

number

required

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

risk_category

string

required

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

factors

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

predicted_churn_date

string

ISO 8601 date string for the predicted churn date.

intervention_recommended

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.

name

string

required

Human-readable name of the experiment.

description

string

Detailed description of the experiment’s purpose.

key

string

required

Unique key used to reference the experiment in code.

status

string

required

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

trafficSplit

number

required

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

startDate

string

ISO 8601 date string for when the experiment starts.

endDate

string

ISO 8601 date string for when the experiment ends.

createdAt

string

required

ISO 8601 date string for when the experiment was created.

updatedAt

string

required

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

variants

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.

name

string

required

Human-readable name of the variant.

key

string

required

Unique key used to reference the variant in code.

description

string

Description of what this variant represents.

isControl

boolean

required

Whether this variant is the control group.

trafficSplit

number

required

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

createdAt

string

required

ISO 8601 date string for when the variant was created.

updatedAt

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

experimentId

string

required

ID of the experiment the user is assigned to.

variantId

string

required

ID of the assigned variant.

variantKey

string

required

Key of the assigned variant.

variantName

string

required

Name of the assigned variant.

isControl

boolean

required

Whether the assigned variant is the control group.

assignedAt

string

required

ISO 8601 date string for when the assignment was made.

experiment

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

Build docs developers (and LLMs) love

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

Build docs developers (and LLMs) love

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