> ## Documentation Index
> Fetch the complete documentation index at: https://docs.priceos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# useTrackUsage

> Track usage events from React via your backend endpoint.

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

<Tip>
  Setup first: see the [React integration guide](/react-integration).
</Tip>

<Tabs>
  <Tab title="Typed">
    ```tsx theme={null}
    const { trackUsage } = useTrackUsage<MyFeatures>()
    ```
  </Tab>

  <Tab title="Untyped">
    ```tsx theme={null}
    const { trackUsage } = useTrackUsage()
    ```
  </Tab>
</Tabs>

## Parameters

<ParamField path="options" type="none">
  `useTrackUsage` does not accept an options argument.
</ParamField>

## Returns

<ParamField path="trackUsage" type="(featureKey | body) => Promise<TrackUsageResponse>">
  Tracks usage and revalidates customer and feature-access caches.
</ParamField>

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

## `trackUsage` body object

<ParamField path="featureKey" type="string" required>
  Feature key to track usage for (typed to your tracked limit feature keys when using generated types).
</ParamField>

<ParamField path="amount" type="number">
  Usage amount to record. Defaults to `1`.
</ParamField>

<ParamField path="eventKey" type="string">
  Stable event key for retries and deduplication.
</ParamField>

<ParamField path="occurredAt" type="number">
  Unix timestamp in milliseconds for when the event happened.
</ParamField>

<ParamField path="metadata" type="Record<string, string>">
  Optional string key/value metadata attached to the usage event.
</ParamField>

<Note>
  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.
</Note>

<Warning>
  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.
</Warning>

## Examples

<Tabs>
  <Tab title="Typed Example">
    ```tsx theme={null}
    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>;
    }
    ```
  </Tab>

  <Tab title="Untyped Example">
    ```tsx theme={null}
    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>;
    }
    ```
  </Tab>
</Tabs>