Gating access to features

Overview

In this quick start guide we’ll demonstrate how to gate access to features.

The functionality that’s included in each plan is defined by a combination of features and their configuration, referred to in Stigg as entitlements.

Before we begin

In order to complete this guide in your application code, please make sure that you have:

• Modeled your pricing in Stigg
• Installed the Stigg JavaScript client SDK
• A Stigg publishable key

Initializing the client SDK

The first step is to initialize Stigg’s client SDK with the publishable key of the environment that’s integrated with Stigg, and the ID of the relevant customer.

The customer ID can usually be retrieved after a customer signs-in or restores their session.

TypeScript

import Stigg from '@stigg/js-client-sdk';

const stiggClient = await Stigg.initialize({ 
    apiKey: 'YOUR_PUBLISHABLE_KEY',
    customerId: "customer-test-id"
});

export default stiggClient; 

Checking whether the customer can access the feature

Gating a metered feature is a 3-step flow: check, gate, and report usage. Doing these in order — and only reporting usage after the action actually happens — is what keeps access checks accurate, especially on features with a small or hard usage limit.

1. Check

Retrieve the customer’s entitlement for the feature using the feature ID that’s defined in Stigg. Pass options.requestedUsage set to the exact amount the customer is about to consume — this evaluates the check against that specific amount before it’s used, rather than against a possibly-stale currentUsage.

TypeScript

const entitlement = stiggClient.getMeteredEntitlement({  
    featureId: "feature-birds",  
    options: { requestedUsage: 3 }  
});  

This example demonstrates a customer’s attempt to use 3 birds of their quota at once.

2. Gate

Use hasAccess on the result to decide whether to allow the action. Only proceed with the action if hasAccess is true — don’t perform the action first and check afterward.

TypeScript

if (entitlement.hasAccess) {  
    console.log("The customer can access the feature!");
    // proceed with the action
} else {
    console.log("The customer has reached their quota.");
    // block the action / prompt to upgrade
}  

Checking entitlement.currentUsage against entitlement.usageLimit yourself, instead of relying on hasAccess (or requestedUsage), can be misleading on features with a hard limit: currentUsage reflects usage as of the last check, not the amount you’re about to add. Always pass the amount you’re about to consume via options.requestedUsage and gate on hasAccess.

3. Report usage

Only report usage for actions the customer actually performed — after step 2 has allowed them through, and after the action has completed. Usage reporting is a backend operation, so it’s done through a backend SDK or the Report Usage API, not the client SDK used for the check above.

Node.js (backend)

await stiggClient.reportUsage({
    customerId: 'customer-test-id',
    featureId: 'feature-birds',
    value: 3, // the amount actually consumed by the action
});

Report usage exactly once per action, for the amount actually consumed. Reporting more than once for the same action, or reporting before the action completes, will overstate usage and can cause access to be denied earlier than expected. If the action fails or is rolled back, don’t report usage for it.

For low-latency, high-volume gating (e.g. every API request), use the Sidecar or a backend SDK with local caching instead of the client SDK — they serve checks from a local cache and keep usage in sync without a network round-trip per check. See local caching and fallback strategy for how checks stay consistent while usage updates propagate to the cache.

Additional resources

Stigg's frontend integration