> 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 # Entitlement & Credit Trigger Webhooks > Fire webhooks when a company approaches or crosses a hard, soft, tier, or credit limit on a feature. Entitlement and credit trigger webhooks fire based on your customers' feature usage, not on data changes. They're useful for notifying your team when customers are approaching or have hit a limit, and for surfacing in-app notifications to customers about their usage. > **Info** > > This page covers usage-based trigger events. For a full list of all webhook events, see [Webhooks](/integrations/webhooks). ## Entitlement trigger events Entitlement triggers fire when a company's usage for a specific feature crosses a threshold: | Event | When it fires | | -------------------------------- | -------------------------------------------------------------------------- | | `entitlement.limit.reached` | Usage reaches the hard limit for a feature (100 percent of the allocation) | | `entitlement.limit.warning` | Usage reaches 80 percent of the hard limit and is still below it | | `entitlement.soft_limit.reached` | Usage reaches the soft limit for a feature | | `entitlement.soft_limit.warning` | Usage reaches 80 percent of the soft limit and is still below it | | `entitlement.tier_limit.reached` | Usage crosses a tier boundary of a tiered feature | | `entitlement.tier_limit.warning` | Usage is 75 percent of the way through the current tier's range | These percentages are fixed. They are not affected by a [usage warning](/feature-management/usage-warnings) set on the entitlement, which is a value your app reads rather than a webhook trigger. Each event fires once per feature per usage period. For trait-based features, which have no usage period, the event fires once per crossing and can fire again after usage falls back below the threshold. **Limit types explained:** * **Hard limit** (`limit`) is the point at which access is restricted. For usage included with a plan, it represents that full usage amount. For [pay as you go](/billing/usage-based-billing#pay-as-you-go) and [overage pricing](/billing/usage-based-billing#fixed-fee-with-overage), it represents a (normally hidden) upper bound of usage you can configure, typically to prevent abuse or runaway spend. * **Soft limit** (`soft_limit`) applies to [overage pricing](/billing/usage-based-billing#fixed-fee-with-overage) and marks the point at which users start being billed for usage. You configure it, and Schematic components show it to the user. * **Tier limit** (`tier_limit`) applies to [tiered pricing](/billing/usage-based-billing#volume-pricing) and fires as a company crosses into each successive pricing tier, letting you notify them of cost changes or prompt an upgrade. ### Setup Entitlement triggers must be configured per feature. When creating or updating a webhook endpoint in Schematic, add one or more entitlement trigger configs, each specifying the `feature_id` you want to monitor. ### Payload The `body` of each entitlement trigger webhook is typed as [`WebFeatureUsageWebhookOutput`](https://github.com/SchematicHQ/schematic-node/blob/main/src/api/types/WebFeatureUsageWebhookOutput.ts) in the Node.js SDK: | Field | Description | | --------------- | --------------------------------------------------------- | | `entitlement` | The entitlement ID that triggered the event | | `feature` | Details about the feature being tracked | | `company` | Details about the company whose usage triggered the event | | `usage` | The company's current usage count | | `allocation` | The feature's allocation (limit) for this company | | `metricResetAt` | When the usage metric resets, if applicable | ### Common use cases * **Internal alerts:** Notify your team in Slack or your CRM when a customer hits a limit, so you can proactively reach out. * **Customer-facing notifications:** Trigger an in-app banner or email to customers when they're nearing or over their limit. ## Credit trigger events Credit triggers fire based on credit usage: | Event | When it fires | | ---------------------- | ---------------------------------------------------------- | | `credit.limit.reached` | A company's credit balance reaches the configured limit | | `credit.limit.warning` | A company's credit balance approaches the configured limit | Credit triggers are configured per credit type, using a `credit_id` in the trigger config when creating or updating a webhook endpoint. ## Credit purchase events This event fires when a company successfully purchases a credit bundle: | Event | When it fires | | ------------------------- | --------------------------------------------------------------- | | `credit.purchase.success` | A credit bundle purchase completes and the grants are committed | ### Payload **`credit.purchase.success`** is typed as [`CreditsCreditPurchaseSuccess`](https://github.com/SchematicHQ/schematic-node/blob/main/src/api/types/CreditsCreditPurchaseSuccess.ts): | Field | Description | | ------------ | ------------------------------------------------ | | `bundleId` | ID of the purchased credit bundle | | `bundleName` | Name of the purchased credit bundle | | `company` | Summary of the purchasing company | | `credit` | Summary of the credit that was topped up | | `grantIds` | IDs of the credit grants created by the purchase | | `quantity` | Number of credits granted by the purchase | ## Auto-topup events These events fire on the outcome of a scheduled credit auto-topup: | Event | When it fires | | --------------------------- | --------------------------------------------------- | | `auto.topup.success` | An auto-topup completes and the credits are granted | | `auto.topup.hard.failure` | An auto-topup attempt fails and will not be retried | | `auto.topup.retry.exceeded` | An auto-topup has failed too many consecutive times | ### Payload **`auto.topup.success`** is typed as [`CreditsAutoTopupSuccess`](https://github.com/SchematicHQ/schematic-node/blob/main/src/api/types/CreditsAutoTopupSuccess.ts): | Field | Description | | ---------- | -------------------------------------------- | | `company` | Summary of the affected company | | `credit` | Summary of the credit that was topped up | | `grantId` | ID of the credit grant created by the top-up | | `quantity` | Number of credits granted by the top-up | **`auto.topup.hard.failure`** is typed as [`CreditsAutoTopupHardFailure`](https://github.com/SchematicHQ/schematic-node/blob/main/src/api/types/CreditsAutoTopupHardFailure.ts): | Field | Description | | ----------------- | ------------------------------------------------------ | | `company` | Summary of the affected company | | `credit` | Summary of the credit that failed to top up | | `errorMessage` | Human-readable error description | | `stripeErrorCode` | Stripe error code, if the failure originated in Stripe | **`auto.topup.retry.exceeded`** is typed as [`CreditsAutoTopupRetryFailure`](https://github.com/SchematicHQ/schematic-node/blob/main/src/api/types/CreditsAutoTopupRetryFailure.ts): | Field | Description | | --------------------- | ------------------------------------------------------------- | | `company` | Summary of the affected company | | `credit` | Summary of the credit that failed to top up | | `consecutiveFailures` | Number of consecutive failed attempts | | `lastErrorMessage` | Human-readable description of the most recent error | | `stripeErrorCode` | Stripe error code from the most recent attempt, if applicable | ### Common use cases * **Internal alerts:** Page your payments or ops team when a customer's auto-topup is failing so you can reach out to update the payment method or remove access if you suspect abuse. * **Customer-facing notifications:** Send a billing failure email to the customer so they can update their payment method.