Stigg Entitlements — Gate Features and Report Usage

This skill covers the runtime side: checking entitlements at request time, reporting usage, and keeping checks reliable when Stigg is briefly unreachable.

Before You Start

Per the umbrella stigg skill: search first. SDK init signatures and entitlement-method names evolve — open the relevant SDK / REST page (Mintlify Stigg docs MCP) before authoring.

The Two Most Important Rules

Rule 1 — Raw events vs calculated usage is by throughput, not by who counts

Stigg accepts usage data through two paths. They look similar; their scaling characteristics are different.

Naming note: the GraphQL mutations / Node SDK methods are reportEvent (raw events) and reportUsage / reportUsageBulk (calculated). Direct REST callers hit POST /api/v1/events and POST /api/v1/usage for the same operations. The shorthand “events.report” / “usage.report” you’ll see used in this skill refers to the conceptual operation, not a specific SDK namespace.

Common misconception: “events” = consumption-y things, “usage” = entitlement-y things. No. The split is operational. Both paths can drive metering and billing. Pick by throughput / latency budget, not by what the data represents.

Rule 2 — Always have a fallback

Entitlement checks are on the critical path of your app. Stigg’s SDKs cache locally and support persistent caches; configure both the cache and the fallback before going to production. See references/fallback.md.

Gating — The Three Entitlement Shapes

Re-check the actual method names in the SDK page you’re targeting — names occasionally evolve (e.g. getEntitlement is also exposed as a unified, generic check on backend SDKs).

Detailed gating patterns — backend / frontend init, per-resource gating, response shape, anti-patterns: references/gating.md.

Frontend (browser) gating

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

// initialize() is SYNCHRONOUS — it returns the client.
// To wait for the client to finish loading, await waitForInitialization().
const stiggClient = Stigg.initialize({
  apiKey: 'client-...',          // publishable key, not server key
  customerId: 'customer-123',
});
await stiggClient.waitForInitialization();

const ent = stiggClient.getMeteredEntitlement({
  featureId: 'api_calls',
  options: { requestedUsage: 1 },
});

if (ent.hasAccess) {
  // allow
} else {
  // show paywall / upgrade prompt
}

For React: wrap in <StiggProvider> and use the hooks the React SDK exposes.

Backend gating

import Stigg from '@stigg/node-server-sdk';

const stigg = await Stigg.initialize({ apiKey: process.env.STIGG_SERVER_API_KEY! });

const ent = await stigg.getMeteredEntitlement({
  customerId: 'customer-123',
  featureId: 'api_calls',
  options: { requestedUsage: 1 },
});

if (!ent.hasAccess) throw new HttpError(402, 'Upgrade required');

For raw REST, the equivalent is GET /api/v1/customers/{id}/entitlements. (The GraphQL query is getEntitlementsState.) See the REST API reference for query params.

Reporting Usage — Pick the Path

Full event-schema field tables, dimension-design guidance, cloud-ingestion paths (S3 / Pub/Sub), and the GraphQL vs direct-REST surface map: references/usage-reporting.md.

Default — Raw events (events.report / reportEvent)

// Backend Node SDK
await stigg.reportEvent({
  events: [{
    customerId: 'customer-123',
    eventName: 'api.request',
    idempotencyKey: 'req-abc-1234',          // required
    dimensions: { region: 'us-east-1', endpoint: '/search' },
    // timestamp is optional; server time is used if omitted
  }],
});

Notes:

• idempotencyKey is required. Events with identical (timestamp, customerId, resourceId, eventName, idempotencyKey) are deduped.
• Dimensions are arbitrary key/value. Add as many as you can up front — they enable future filtering / aggregation without backfill.
• Max payload per event: 1 MB.
• resourceId is required when the product allows multiple subscriptions (workspaces, projects).

Set / delta — Calculated usage (usage.report / reportUsage)

import { UsageUpdateBehavior } from '@stigg/node-server-sdk';

// "Customer now has 5 seats" — Set behavior
await stigg.reportUsage({
  customerId: 'customer-123',
  featureId: 'seats',
  value: 5,
  updateBehavior: UsageUpdateBehavior.SET,
});

// "+2 seats" — Delta behavior (default)
await stigg.reportUsage({
  customerId: 'customer-123',
  featureId: 'seats',
  value: 2,
  // updateBehavior defaults to DELTA
});

Use this when your app has the authoritative value (seat counts, configured quotas) and you don’t want Stigg aggregating per-event.

Bulk variant (reportUsageBulk) supports up to 100 measurements per call — note its rate limit.

Cache + Fallback — Required for Production

Stigg SDKs cache effective entitlements locally so checks don’t pay a network round trip on every request. Configure the cache and the fallback before production:

• Local in-memory cache — default in all SDKs. Refreshed via polling (frontend) or real-time updates (backend).
• Persistent cache — for serverless / large fleets where in-memory caches die with the process. Backed by Redis via the persistent-cache-service. Supported in Node SDK + Sidecar.
• Sidecar — a separate process / deployment that fronts the API. Lower latency, offline mode, global fallback.
• Fallback rules — global and per-entitlement. When entitlement data is missing or Stigg is unreachable, the SDK returns the configured fallback (allow / deny, with a marker so you can log).
• Usage during outages — entitlement checks keep working from cache; usage reports buffer in-memory (or in the persistent cache) and flush on reconnect.

Full guidance: references/fallback.md.

Promotional Entitlements

Per-customer entitlement overrides — granted directly to a customer, outside any subscription. Owned by this skill end-to-end (granting, revoking, reading) since they’re per-customer runtime concerns, not catalog modeling.

• Use cases: temporary limit increases (“oops, your script blew through your API quota — here’s an extra 1k for the rest of the period”), early access to a premium feature for a specific customer, enterprise accommodations, goodwill gestures.
• Additive with plan and add-on entitlements (the generous-entitlement rule applies).
• Time-bounded (1 month / 1 year / lifetime) or until manually revoked.
• Granting is a mutation — grantPromotionalEntitlements (GraphQL) / equivalent SDK method / available in the MCP. Pass customerId, featureId, the override value, and the period.
• Revoking uses revokePromotionalEntitlement.

Modeling shape (which features exist) lives in stigg-pricing-modeling; promotional entitlements just override configuration on those features for a specific customer.

When NOT to Use This Skill

• Modeling features / plans / add-ons → stigg-pricing-modeling.
• Provisioning / canceling / migrating subscriptions → stigg-subscriptions.
• Granting credit balances at runtime → stigg-credits.
• Picking the right pricing model for the customer’s product → stigg-pricing-expert.

Common Mistakes