useTrackUsage

The useTrackUsage hook returns a function for writing usage events for tracked limit features.

Setup first: see the React integration guide.

Typed
Untyped

const { trackUsage } = useTrackUsage<MyFeatures>()

const { trackUsage } = useTrackUsage()

Parameters

none

useTrackUsage does not accept an options argument.

Returns

(featureKey | body) => Promise<TrackUsageResponse>

Tracks usage and revalidates customer and feature-access caches.

You can call it as trackUsage("team_seats") (defaults amount to 1) or pass a full body object.

`trackUsage` body object

string

required

Feature key to track usage for (typed to your tracked limit feature keys when using generated types).

number

Usage amount to record. Defaults to 1.

string

Stable event key for retries and deduplication.

number

Unix timestamp in milliseconds for when the event happened.

Record<string, string>

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>;
}

Components

React Hooks

Misc

Parameters

Returns

`trackUsage` body object

Examples

​Parameters

​Returns

​trackUsage body object

​Examples

Parameters

Returns

`trackUsage` body object

Examples