Creating a metered feature

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 simply goes up, and/or is metered on a perodic 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.

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.

1
from schematic import Schematic
2
3
client = Schematic(
4
    api_key = "your-api-key"
5
)
6
7
user = {
8
    "your-user-key" : "value"
9
}
10
11
company = {
12
    "your-company-key" : "value"
13
}
14
15
# send track event
16
response  = client.track(
17
    event="new-event",
18
    user=user,
19
    company=company
20
)

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 an 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.

1
from schematic import Schematic
2
3
client = Schematic(
4
    api_key = "your-api-key"
5
)
6
7
# upsert company in Schematic
8
response = client.companies.upsert_company(
9
    keys={
10
        "your-company-key" : "value"
11
    },
12
    traits = {
13
        "new-trait" : 3
14
    }
15
)

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.

1
from schematic import Schematic
2
3
client = Schematic(
4
    api_key = "your-api-key"
5
)
6
7
company = {
8
   "your-company-key" : "value"
9
}
10
11
# key associated with feature
12
feature_key = "new-trait-based-feature"
13
14
# retrieve latest flag evaluation
15
response = client.features.check_flag(
16
    feature_key = feature_key,
17
    company = company
18
)