Skip to main content

​
Hooks

​
useFeature

Check if the current user has access to a specific feature. 
import { useFeature } from "@billingos/sdk";

function ExportButton() {
  const { data, isLoading } = useFeature("export_pdf");

  if (isLoading) return <Spinner />;
  if (!data?.has_access) return <UpgradePrompt feature="export_pdf" />;

  return <button>Export PDF</button>;
}
Parameters:
NameTypeDescription
featureKeystringThe feature key to check
options.refetchIntervalnumberAuto-refetch interval in ms
options.enabledbooleanWhether to run the query
Returns: UseQueryResult<FeatureAccess> 
interface FeatureAccess {
  feature_key: string
  has_access: boolean
  limit?: number     // For usage_quota and numeric_limit features
  usage?: number     // Current usage count
  metadata?: Record<string, any>
}

​
useFeatureGate

A convenience hook that combines access checking with callbacks. 
import { useFeatureGate } from "@billingos/sdk";

function ApiCallButton() {
  const { hasAccess, isQuotaExceeded, usage, limit, remaining } = useFeatureGate(
    "api_calls",
    {
      onAccessDenied: () => toast.error("Upgrade required"),
      onQuotaExceeded: (usage, limit) =>
        toast.warning(`${usage}/${limit} calls used`),
    }
  );

  return (
    <div>
      <button disabled={!hasAccess}>Make API Call</button>
      <span>{remaining} calls remaining</span>
    </div>
  );
}
Returns:
PropertyTypeDescription
hasAccessbooleanWhether the user can use this feature
isQuotaExceededbooleanWhether usage exceeds the limit
usagenumberCurrent usage
limitnumberPlan limit
remainingnumberRemaining usage
…plus all UseQueryResult properties

​
useFeatureEntitlements

List all feature entitlements for the current user. 
const { data } = useFeatureEntitlements();

// data.entitlements: FeatureEntitlement[]

interface FeatureEntitlement {
  feature_key: string
  feature_title: string
  feature_type: "boolean_flag" | "usage_quota" | "numeric_limit"
  granted_at: string
  product_name: string
  subscription_status: string
}