> If you are setting up, configuring, or answering questions about Schematic, connect the
> Schematic MCP server before working from these pages. It reads and writes plans, features,
> entitlements, and overrides against the real account, so what you report and what you build
> match what actually exists.
>
> The server is at https://api.schematichq.com/mcp
>
> From Claude, ChatGPT, or another chat assistant, add it as a custom connector:
> https://docs.schematichq.com/working-with-ai
>
> From a coding assistant such as Claude Code, Codex, or Cursor:
> https://docs.schematichq.com/building-with-ai
>
> For clean Markdown of any page, append `.md` to the page URL. For a complete page index,
> see https://docs.schematichq.com/llms.txt

# Usage Warnings

> Set a warning value on a plan entitlement so your app can tell customers they are approaching a limit before they hit it.

A usage warning is a value you set on a plan entitlement, below its limit and in the same units as usage. Schematic stores the value and returns it alongside the entitlement. It does not send a notification, throttle, or block when usage crosses it. Your app reads the value and decides what to show.

Each entitlement can carry one usage warning. Leaving it empty changes nothing about how the entitlement behaves.

## When to use it

Without a usage warning, the first signal a customer gets about a limit is usually the moment access turns off. A usage warning gives your app a number to warn at that lives in Schematic rather than in your code, so it can differ per plan and stays visible in the dashboard.

It also supports a fair-use pattern. Say a plan advertises 100 AI conversations a month but you are happy to let a customer run to 120 before cutting them off. Set the entitlement limit to 120 and the usage warning to 100. The flag turns off at 120 like any other limit. Your app shows 100 as the plan's number, warns when usage passes it, and [Schematic components](#show-the-warning-value-in-components) can display 100 as the limit.

## Set a usage warning

### In the dashboard

Open a plan entitlement from the feature or from the plan. For an entitlement that is included in the plan and has a numeric limit, the editor shows a **Usage warning** field. Enter a value below the limit and save.

The field is not shown for unlimited entitlements, boolean entitlements, or entitlements priced as pay as you go or overage.

### With the API

Pass a `warning_tiers` array when you [create](/api-reference/entitlements/create-plan-entitlement) or [update](/api-reference/entitlements/update-plan-entitlement) a plan entitlement:

```json
{
  "feature_id": "feat_...",
  "plan_id": "plan_...",
  "value_type": "numeric",
  "value_numeric": 120,
  "metric_period": "current_month",
  "warning_tiers": [
    { "key": "default", "value": 100 }
  ]
}
```

The array holds at most one entry. Use the key `default`. The dashboard writes that key and components read it, so a tier under any other key is stored and returned but does not appear in the dashboard field and is ignored by components.

The value is a whole number of at least 1, in the entitlement's usage units. Schematic does not check it against the limit, so keep it below the limit yourself.

The entitlement needs a usage limit to warn against: a numeric limit, a trait-based limit, or a credit-based value. Setting a warning tier on a boolean or unlimited entitlement returns a 400.

On update, omitting `warning_tiers` leaves the stored value alone. Sending an empty array clears it.

Plan entitlement responses include the configured tiers:

```json
"warning_tiers": [
  { "id": "pltlwt_...", "key": "default", "value": 100 }
]
```

## Read the warning value

### Check flag response

When a [flag check](/api-reference/features/check-flag) matches a feature entitlement rule, the response includes the entitlement under `entitlement`, and its `warning_tiers` carry the configured value:

```json
{
  "value": true,
  "feature_usage": 104,
  "feature_allocation": 120,
  "entitlement": {
    "feature_key": "ai-conversations",
    "value_type": "numeric",
    "warning_tiers": [
      { "key": "default", "value": 100 }
    ]
  }
}
```

Compare `feature_usage` to the tier value to decide whether the customer is approaching the limit.

### In a frontend SDK

The frontend SDKs return the tiers as `warningTiers` on the entitlement, each a `{ key, value }` pair in the entitlement's usage units. The field is `undefined` when no warning is configured, so read the `default` key and compare it to `featureUsage`:

**`React`**

```tsx title="React"
import { useSchematicEntitlement } from "@schematichq/schematic-react";

const AiConversations = () => {
  const { featureUsage, warningTiers } =
    useSchematicEntitlement("ai-conversations");

  const warning = warningTiers?.find((tier) => tier.key === "default");
  const approachingLimit =
    typeof featureUsage === "number" &&
    typeof warning?.value === "number" &&
    featureUsage >= warning.value;

  return (
    <>
      {approachingLimit && (
        <Banner>You have used {featureUsage} of your {warning.value} conversations.</Banner>
      )}
      <Conversations />
    </>
  );
};
```

**`Vue`**

```vue title="Vue"
<script setup lang="ts">
import { computed } from "vue";
import { useSchematicEntitlement } from "@schematichq/schematic-vue";

const { featureUsage, warningTiers } =
  useSchematicEntitlement("ai-conversations");

const warning = computed(() =>
  warningTiers.value?.find((tier) => tier.key === "default"),
);
const approachingLimit = computed(
  () =>
    typeof featureUsage.value === "number" &&
    typeof warning.value?.value === "number" &&
    featureUsage.value >= warning.value.value,
);
</script>

<template>
  <Banner v-if="approachingLimit">
    You have used {{ featureUsage }} of your {{ warning!.value }} conversations.
  </Banner>
  <Conversations />
</template>
```

**`Angular`**

```typescript title="Angular"
import { Component, inject } from "@angular/core";
import { map } from "rxjs";
import { SchematicService } from "@schematichq/schematic-angular";

@Component({
  selector: "app-ai-conversations",
  template: `
    @if (approachingLimit$ | async) {
      <app-banner />
    }
    <app-conversations />
  `,
})
export class AiConversationsComponent {
  private schematic = inject(SchematicService);
  approachingLimit$ = this.schematic.entitlement$("ai-conversations").pipe(
    map((entitlement) => {
      const warning = entitlement.warningTiers?.find(
        (tier) => tier.key === "default",
      );
      return (
        typeof entitlement.featureUsage === "number" &&
        typeof warning?.value === "number" &&
        entitlement.featureUsage >= warning.value
      );
    }),
  );
}
```

**`JavaScript`**

```typescript title="JavaScript"
const check = schematic.getFlagCheck("ai-conversations");
const warning = check?.warningTiers?.find((tier) => tier.key === "default");

if (
  typeof check?.featureUsage === "number" &&
  typeof warning?.value === "number" &&
  check.featureUsage >= warning.value
) {
  showBanner(check.featureUsage, warning.value);
}
```

Requires `@schematichq/schematic-js` 1.8.0 or later, or the framework SDK version built on it.

### Show the warning value in components

Schematic components can display the usage warning in place of the hard limit. Set `warningThresholdConfig` on `EmbedProvider`:

```tsx
import { EmbedProvider, SchematicEmbed } from "@schematichq/schematic-components";

<EmbedProvider warningThresholdConfig={{ showAsLimit: true }}>
  <SchematicEmbed accessToken={accessToken} id={componentId} />
</EmbedProvider>
```

With `showAsLimit` on, usage meters, included feature usage details, the plan manager, the pricing table, and checkout show the warning value as the entitlement's limit. Entitlements without a usage warning keep showing their hard limit. The option defaults to off and requires `@schematichq/schematic-components` 2.21.0 or later.

## Usage warnings and webhooks

The usage warning you set here and the `entitlement.limit.warning` webhook are separate mechanisms. The webhook fires at its own threshold, which you can read about in [Entitlement & Credit Trigger Webhooks](/integrations/webhooks/entitlement-triggers).