Skip to main content

​
Hooks

​
useTrackUsage

Track a usage event (e.g., an API call, a file upload, a team member added). 
import { useTrackUsage } from "@billingos/sdk";

function ApiCallButton() {
  const { mutateAsync: trackUsage } = useTrackUsage();

  const handleApiCall = async () => {
    const result = await makeApiCall();

    await trackUsage({
      featureKey: "api_calls",
      quantity: 1,
    });
  };

  return <button onClick={handleApiCall}>Make API Call</button>;
}
Input:
NameTypeRequiredDescription
featureKeystringYesWhich feature was used
quantitynumberYesHow many units to track
metadataRecord<string, any>NoAdditional context

​
useUsageMetrics

Fetch usage metrics for the current user. Auto-refreshes every 30 seconds. 
import { useUsageMetrics } from "@billingos/sdk";

function UsageDashboard() {
  const { data } = useUsageMetrics("api_calls");

  return (
    <div>
      {data?.metrics.map((metric) => (
        <div key={metric.feature_key}>
          <p>{metric.feature_title}</p>
          <p>{metric.consumed} / {metric.limit} used</p>
          <p>{metric.remaining} remaining</p>
          <p>Resets in {metric.resets_in_days} days</p>
        </div>
      ))}
    </div>
  );
}
Parameters:
NameTypeDescription
featureKeystringOptional — filter to a specific feature
Returns: UseQueryResult<{ metrics: UsageMetric[] }> 
interface UsageMetric {
  feature_key: string
  feature_title: string
  product_name: string
  consumed: number
  limit: number
  remaining: number
  percentage_used: number
  period_start: string
  period_end: string
  resets_in_days: number
}

​
useFeatureEntitlements

Fetch all feature entitlements for the current user. 
import { useFeatureEntitlements } from "@billingos/sdk";

const { data } = useFeatureEntitlements();
// data.entitlements: FeatureEntitlement[]

​
Example: Track with idempotency

For scenarios where duplicate events could occur, include metadata for deduplication: 
await trackUsage({
  featureKey: "api_calls",
  quantity: 1,
  metadata: {
    idempotency_key: `api-call-${requestId}`,
    endpoint: "/api/data",
  },
});