Implementation:Helicone Helicone UseFeatureTrial

Knowledge Sources	Helicone
Domains	Billing, Feature Access
Last Updated	2026-02-14 06:32 GMT

Overview

A React hook for managing feature trial activation and subscription upgrades, enabling users to try premium features or upgrade their plan through Stripe integration.

Description

The useFeatureTrial hook encapsulates the complete workflow for activating feature trials and handling subscription upgrades. It supports three product types: prompts, experiments, and evals.

Internal behavior:

Subscription query -- Uses TanStack Query to fetch the organization's current subscription status from /v1/stripe/subscription via the Jawn client.

Pro requirement check -- Determines if the organization needs a Pro plan upgrade by checking if their tier is "free" or "growth". This flag (proRequired) controls whether the activation flow triggers a plan upgrade or an addon addition.

Mutation logic -- The mutation handles three distinct flows:
- Team Bundle upgrade -- If the user selects "Team Bundle", it calls the appropriate endpoint based on whether they are an existing customer (with canceled subscription or on a pro tier) or a new customer.
- Pro upgrade with addon -- If the user is on a free/growth tier, it triggers a Pro plan upgrade with the specified addon included, routing to either the existing-customer or new-customer upgrade endpoint.
- Addon addition -- If the user is already on Pro, it simply adds the addon via /v1/stripe/subscription/add-ons/{productType}.

handleConfirmTrial -- Orchestrates the mutation and handles the result. Redirect-type results open the Stripe checkout URL in a new tab. Refresh-type results show a success notification, refetch the subscription data, and reload the page.

Usage

Use this hook in feature trial dialogs and upgrade prompts. It provides the handleConfirmTrial callback for the confirmation button, the proRequired flag for conditional UI rendering, and the mutation/subscription query objects for loading state management.

Code Reference

Source Location

Repository: Helicone
File: web/hooks/useFeatureTrial.ts

Signature

export const useFeatureTrial = (
  productType: "prompts" | "experiments" | "evals",
  featureName: string
) => {
  // Returns:
  handleConfirmTrial: (selectedPlan?: string) => Promise<{ success: boolean; requiresRedirect?: boolean }>;
  proRequired: boolean;
  mutation: UseMutationResult<...>;
  subscription: UseQueryResult<...>;
};

Import

import { useFeatureTrial } from "@/hooks/useFeatureTrial";

I/O Contract

Input (Parameters)

Parameter	Type	Description
`productType`	"experiments" \| "evals"	The addon product type to activate
`featureName`	`string`	Human-readable feature name for notification messages

Output (Return)

Field	Type	Description
`handleConfirmTrial`	`(selectedPlan?: string) => Promise<{ success: boolean; requiresRedirect?: boolean }>`	Callback to trigger trial activation or plan upgrade
`proRequired`	`boolean`	Whether the user needs a Pro plan upgrade before accessing the feature
`mutation`	`UseMutationResult`	TanStack Query mutation object for loading/error state
`subscription`	`UseQueryResult`	TanStack Query result for the current subscription data

API Endpoints Used

Endpoint	Method	Purpose
`/v1/stripe/subscription`	GET	Fetch current subscription status
`/v1/stripe/subscription/new-customer/upgrade-to-pro`	POST	Upgrade new customer to Pro with addons
`/v1/stripe/subscription/existing-customer/upgrade-to-pro`	POST	Upgrade existing customer to Pro with addons
`/v1/stripe/subscription/new-customer/upgrade-to-team-bundle`	POST	Upgrade new customer to Team Bundle
`/v1/stripe/subscription/existing-customer/upgrade-to-team-bundle`	POST	Upgrade existing customer to Team Bundle
`/v1/stripe/subscription/add-ons/{productType}`	POST	Add individual addon to existing Pro plan

Usage Examples

import { useFeatureTrial } from "@/hooks/useFeatureTrial";

function FeatureTrialDialog() {
  const { handleConfirmTrial, proRequired, mutation } = useFeatureTrial(
    "experiments",
    "Experiments"
  );

  const onConfirm = async (selectedPlan?: string) => {
    const result = await handleConfirmTrial(selectedPlan);
    if (result.success && !result.requiresRedirect) {
      // Trial activated successfully, page will reload
    }
  };

  return (
    <div>
      {proRequired && <p>A Pro plan upgrade is required.</p>}
      <button
        onClick={() => onConfirm()}
        disabled={mutation.isPending}
      >
        {mutation.isPending ? "Activating..." : "Start Trial"}
      </button>
    </div>
  );
}

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment