Usage Warnings

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 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 or update a plan entitlement:

{
  "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:

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

Read the warning value

Check flag response

When a flag check matches a feature entitlement rule, the response includes the entitlement under entitlement, and its warning_tiers carry the configured value:

{
  "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:

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

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:

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.