The useTrackUsage hook returns a function for writing usage events for tracked limit features.
const { trackUsage } = useTrackUsage<MyFeatures>()
const { trackUsage } = useTrackUsage()
Parameters
useTrackUsage does not accept an options argument.
Returns
trackUsage
(featureKey | body) => Promise<TrackUsageResponse>
Tracks usage and revalidates customer and feature-access caches.
trackUsage("team_seats") (defaults amount to 1) or pass a full body object.
trackUsage body object
Feature key to track usage for (typed to your tracked limit feature keys when using generated types).
Usage amount to record. Defaults to 1.
Stable event key for retries and deduplication.
Unix timestamp in milliseconds for when the event happened.
Optional string key/value metadata attached to the usage event.
If the action happens on your backend (for example in a server action, webhook, or background job), it usually makes more sense to track usage on the backend.
When using built-in Next.js handlers (priceos/next), client hook calls must use a positive amount.
For negative adjustments, track usage on your backend with the Node.js SDK or REST API.
Examples
Typed Example
Untyped Example
import { useTrackUsage } from "priceos/react";
import type { MyFeatures } from "./priceos.types";
export function AddSeatButton() {
const { trackUsage } = useTrackUsage<MyFeatures>();
async function onClick() {
await trackUsage({
featureKey: "team_seats",
amount: 1,
eventKey: `add_team_seat_${Date.now()}`,
metadata: {
action: "add_team_seat",
},
});
}
return <button onClick={onClick}>Add teammate</button>;
}
import { useTrackUsage } from "priceos/react";
export function AddSeatButton() {
const { trackUsage } = useTrackUsage();
async function onClick() {
await trackUsage({
featureKey: "team_seats",
amount: 1,
eventKey: `add_team_seat_${Date.now()}`,
metadata: {
action: "add_team_seat",
},
});
}
return <button onClick={onClick}>Add teammate</button>;
}
