> 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

# Creating a metered feature with Schematic

> Metered features have a pre-defined limit either set globally or on a per-company basis. This is a common packaging model and is often paired with boolean features.

## What is a metered feature?

Metered features are features that have a pre-defined limit either set globally or on a per-company basis. This is a common packaging model in SaaS, and is often paired with features that may simply be on or off.

## Trait-based vs. Event-based features

There are two types of metered features in Schematic - trait-based and event-based.

### Trait-based features

**Trait-based** features are best suited for resource utilization that could increase or decrease. Some examples of features that fit this criteria are seats, projects, devices, etc. Traits should be upserted on company profiles to specify utilization against a pre-defined limit at the feature level.

### Event-based features

**Event-based** features are best suited for resource utilization that is metered on a periodic basis (e.g. per day, per week, per month). Some examples of features that fit this criteria are API requests, queries, etc. Individual events should be sent into Schematic, which will be automatically aggregated to calculate utilization against a pre-defined limit at the feature level.

Event-based features also support **negative quantities** for adjustments such as refunds or corrections. Negative quantity events must be submitted using a secret API key. See [Negative Quantities](/billing/usage-based-billing#negative-quantities-usage-adjustments) for details.

For importing historical usage or correcting events with stale timestamps, see [Backfills and usage corrections](/playbooks/backfill-and-corrections).

To safely retry network calls without double-counting usage, you can submit an optional `idempotency_key` with each event. Duplicate events with the same key, scoped to the same environment and event type, are dropped for 24 hours. See the [Event object](/api-reference/events/the-event-object#idempotency_key) for details.

> **Info**
>
> You can read more about feature types [here](/feature-management/feature-types).

## Setting up an Event-based metered feature

To set up an event-based metered feature, do the following:

1. Create a Feature and choose "Event-based" in the control dropdown
2. Follow the wizard to create a corresponding flag and specify an event key to track utilization
3. Send in events using the event key specified in the wizard

Here's an example of sending in utilization events for a company and then using the entitlement details to show usage vs. limit and whether more usage is allowed.

```ts
import { SchematicClient } from "@schematichq/schematic-typescript-node";

const apiKey = process.env.SCHEMATIC_API_KEY;
const client = new SchematicClient({ apiKey });

const user = { "your-user-key": "value" };
const company = { "your-company-key": "value" };

// Send track event to record utilization
await client.track({
  event: "new-event",
  user,
  company,
});

// Check the feature flag with entitlement details (usage, allocation)
const resp = await client.checkFlagWithEntitlement(
  { company, user },
  "new-event-based-feature"
);

console.log(`Usage: ${resp.entitlement.usage} of ${resp.entitlement.allocation}`);
console.log(resp.value ? "More usage allowed" : "Limit hit");
```

## Setting up a Trait-based metered feature

To set up a trait-based metered feature, do the following:

1. Create a Feature and choose "Trait-based" in the control dropdown
2. Follow the wizard to create a corresponding flag and specify a trait key to track utilization
3. Upsert traits using the event key specified in the wizard

Here's an example of updating a utilization trait value for a company.

```python
from schematic import Schematic

client = Schematic(
    api_key = "your-api-key"
)

# upsert company in Schematic
response = client.companies.upsert_company(
    keys={
        "your-company-key" : "value"
    },
    traits = {
        "new-trait" : 3
    }
)
```

## Entitlement options

Once you've created a feature, you can entitle it to a plan and specify a limit. If you think of the event or trait you selected when you created the feature as the numerator of your meter, the limit you select when creating an entitlement is functionally the denominator. You'll have three options for each entitlement you create for a feature:

1. **Numerical limit** - Schematic will apply the same limit to every company with the entitlement. For example, if you set the numerical limit as 5, all companies that have this entitlement can utilize up to 5 of the feature.
2. **No limit** - Schematic will not apply a limit to any company with the entitlement. For example, all companies that have this entitlement will have no limit to their usage of the feature.
3. **Trait** - Schematic will refer to a trait at the company level to apply a limit, and the value of the limit can differ by company (e.g. for scenarios such as custom limits sold in a sales process, or defined by the user in the product). For example, if you set the dynamic limit as a trait named `seats_allocated`, all companies that have this entitlement can utilize up to the number of `seats_allocated` for the feature -- this can be different from company to company.

## Integrating with a metered feature in Schematic

Integrating a metered feature from Schematic into your application is the same as integrating a feature that is simply on or off. The following code will retrieve a flag evaluation based on the entitlement policy you set up in Schematic, and no additional metering logic needs to be added to your application code to store utilization or compare utilization against limits.

```python
from schematic import Schematic

client = Schematic(
    api_key = "your-api-key"
)

company = {
   "your-company-key" : "value"
}

# key associated with feature
feature_key = "new-trait-based-feature"

# retrieve latest flag evaluation
response = client.features.check_flag(
    feature_key = feature_key,
    company = company
)
```

> Metered features have a pre-defined limit either set globally or on a per-company basis. This is a common packaging model and is often paired with boolean features.