Governance check and ingest - Stigg Documentation

Governance exposes two runtime operations: Check and Ingest.

Check reads the current usage and returns a gate decision. It never modifies state.
Ingest records a consumption event and increments the usage counter. It never gates.

The typical pattern is: check → allow or deny based on isGranted → ingest (only if allowed).

Governance is opt-in. If an entity has no assignment for the requested capability, Check returns isGranted: true with an empty chains array. There is no default deny.

Both Check and Ingest are fail-closed. If the governance cache is unavailable, they return 503 Service Unavailable rather than silently allowing or skipping. Plan for this in your error handling — a 503 from governance should be treated the same as any upstream dependency outage.

If you haven’t initialized the client yet, see Setting up governance.

import Stigg from '@stigg/typescript';

const client = new Stigg({ apiKey: process.env.STIGG_API_KEY });

Check

GET /api/v1-beta/customers/:id/entitlements/check Returns whether the requested amount of a feature or credit is permitted, along with current usage and the applicable limit. Call this before allowing consumption.

By feature

Pass the feature ID and dimensions that identify the governed entities. The governance engine resolves the entity hierarchy from the dimensions automatically.

const response = await client.v1Beta.customers.entitlements.check('cus-acme', {
  featureId:      'feature-ai-tokens',
  requestedUsage: 1000,
  dimensions:     { teamId: 'team-eng' },
});

if (!response.data.isGranted) {
  throw new Error('Usage limit reached');
}

curl "https://api.stigg.io/api/v1-beta/customers/cus-acme/entitlements/check?featureId=feature-ai-tokens&requestedUsage=1000&dimensions[teamId]=team-eng" \
  -H "X-API-KEY: <SERVER_API_KEY>"

By credit

Use currencyId instead of featureId to check against a credit balance limit.

const response = await client.v1Beta.customers.entitlements.check('cus-acme', {
  currencyId:     'currency-ai-tokens',
  requestedUsage: 1000,
  dimensions:     { teamId: 'team-eng' },
});

if (!response.data.isGranted) {
  throw new Error('Usage limit reached');
}

curl "https://api.stigg.io/api/v1-beta/customers/cus-acme/entitlements/check?currencyId=currency-ai-tokens&requestedUsage=1000&dimensions[teamId]=team-eng" \
  -H "X-API-KEY: <SERVER_API_KEY>"

Pass either featureId or currencyId, not both.

Check request fields

Field	Type	Required	Description
`featureId`	`string`	one of	The Stigg feature ID to check. Mutually exclusive with `currencyId`.
`currencyId`	`string`	one of	The Stigg credit currency ID to check. Mutually exclusive with `featureId`.
`dimensions`	`object`	no	Non-empty key-value map. The engine resolves governed entities by matching keys against entity type `attributionKeys`.
`requestedUsage`	`number`	no	Amount the caller intends to consume. Defaults to `1`.

Check response

200 OK:

{
  "data": {
    "isGranted": true,
    "type": "FEATURE",
    "accessDeniedReason": null,
    "feature": {
      "id": "feature-ai-tokens",
      "displayName": "AI Tokens",
      "featureType": "NUMBER",
      "featureStatus": "ACTIVE"
    },
    "usageLimit": 200000,
    "hasUnlimitedUsage": false,
    "resetPeriod": "MONTH",
    "currentUsage": 42311,
    "chains": [
      [
        {
          "entityId": "team-eng",
          "scopeEntityIds": [],
          "usageLimit": 200000,
          "currentUsage": 42311,
          "isGranted": true
        },
        {
          "entityId": "org-acme",
          "scopeEntityIds": [],
          "usageLimit": 1000000,
          "currentUsage": 87450,
          "isGranted": true
        }
      ]
    ]
  }
}

Field	Description
`isGranted`	Top-level gate decision. `true` when every budget in every chain allows the request.
`type`	Entitlement type: `FEATURE` or `CREDIT`.
`usageLimit`	Limit configured for this customer. `null` means usage is tracked but the limit never blocks.
`currentUsage`	Consumed in the active reset period.
`resetPeriod`	The reset cadence (e.g. `MONTH`).
`chains[]`	Per-entity budget chains for this check. Present only when governance is active for the customer.
`chains[][].entityId`	Entity at this node in the hierarchy.
`chains[][].scopeEntityIds`	Scope that matched. `[]` is the node-wide budget.
`chains[][].usageLimit`	Hard limit; `null` means usage is tracked but never blocks.
`chains[][].currentUsage`	Consumed in the active cadence period.
`chains[][].isGranted`	`currentUsage + requestedUsage <= usageLimit`.

Finding the binding constraint

const response = await client.v1Beta.customers.entitlements.check('cus-acme', {
  featureId:      'feature-ai-tokens',
  requestedUsage: 500,
  dimensions:     { teamId: 'team-eng' },
});

if (!response.data.isGranted) {
  const denied = response.data.chains
    ?.flat()
    .find((node) => !node.isGranted);

  return {
    allowed:   false,
    entityId:  denied?.entityId,
    remaining: denied ? (denied.usageLimit ?? 0) - denied.currentUsage : 0,
  };
}

Ingest

Records consumption and increments the usage counter. Ingest never gates — call Check first if you need a permit decision before consuming. Use reportUsage for synchronous, real-time enforcement — credit-backed features return an updated balance in the response immediately. Use reportEvent for high-volume, eventually-consistent metering (≈10 s latency) where a real-time balance is not required.

reportUsage

await client.v1.usage.report({
  usages: [
    {
      customerId: 'cus-acme',
      featureId:  'feature-ai-tokens',
      value:      1250,
      dimensions: { teamId: 'team-eng' },
    },
  ],
});

curl -X POST https://api.stigg.io/api/v1/usage \
  -H "X-API-KEY: <SERVER_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "usages": [
      {
        "customerId": "cus-acme",
        "featureId": "feature-ai-tokens",
        "value": 1250,
        "dimensions": { "teamId": "team-eng" }
      }
    ]
  }'

reportEvent

await client.v1.events.report({
  events: [
    {
      customerId:     'cus-acme',
      eventName:      'ai-tokens-consumed',
      idempotencyKey: crypto.randomUUID(),
      dimensions:     { teamId: 'team-eng', tokenCount: 1250 },
    },
  ],
});

curl -X POST https://api.stigg.io/api/v1/events \
  -H "X-API-KEY: <SERVER_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "customerId": "cus-acme",
        "eventName": "ai-tokens-consumed",
        "idempotencyKey": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "dimensions": { "teamId": "team-eng", "tokenCount": 1250 }
      }
    ]
  }'

Batching usage reports

Both reportUsage and reportEvent accept up to 100 records per request.

await client.v1.usage.report({
  usages: [
    { customerId: 'cus-acme', featureId: 'feature-api-calls', value: 1,    dimensions: { teamId: 'team-eng' } },
    { customerId: 'cus-acme', featureId: 'feature-ai-tokens', value: 2500, dimensions: { teamId: 'team-eng' } },
  ],
});

curl -X POST https://api.stigg.io/api/v1/usage \
  -H "X-API-KEY: <SERVER_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "usages": [
      { "customerId": "cus-acme", "featureId": "feature-api-calls", "value": 1,    "dimensions": { "teamId": "team-eng" } },
      { "customerId": "cus-acme", "featureId": "feature-ai-tokens", "value": 2500, "dimensions": { "teamId": "team-eng" } }
    ]
  }'

Ingest fields

Field	Type	Required	Description
`customerId`	`string`	yes	The Stigg customer ID.
`featureId`	`string`	yes	The Stigg feature or credit ID to increment.
`value`	`number`	yes	Non-negative integer. Amount to add.
`dimensions`	`object`	no	Key-value map used for governance entity attribution. Values can be `string`, `number`, or `boolean`.

Full check-then-ingest pattern

async function consumeTokens(
  customerId: string,
  teamId:     string,
  tokenCount: number,
): Promise<{ allowed: boolean; remaining?: number }> {
  // 1. Check before consuming
  const response = await client.v1Beta.customers.entitlements.check(customerId, {
    featureId:      'feature-ai-tokens',
    requestedUsage: tokenCount,
    dimensions:     { teamId },
  });

  if (!response.data.isGranted) {
    const denied = response.data.chains?.flat().find((n) => !n.isGranted);
    return { allowed: false, remaining: denied ? (denied.usageLimit ?? 0) - denied.currentUsage : 0 };
  }

  // 2. Proceed with the operation …

  // 3. Ingest after consuming
  await client.v1.usage.report({
    usages: [{ customerId, featureId: 'feature-ai-tokens', value: tokenCount, dimensions: { teamId } }],
  });

  return { allowed: true };
}

Getting started

Developer tools

Governance (Private Beta)

Modeling your pricing in Stigg

Managing customers, subscriptions and entitlements

Getting usage data into Stigg

Snap-in widgets

Native integrations

Importing and exporting data

Going live

Workflow automation

Rolling out pricing changes with confidence

Price localization

Managing your account

High-availability and scale

Security & compliance

Check and ingest

Check

By feature

By credit

Check request fields

Check response

Finding the binding constraint

Ingest

reportUsage

reportEvent

Batching usage reports

Ingest fields

Full check-then-ingest pattern

​Check

​By feature

​By credit

​Check request fields

​Check response

​Finding the binding constraint

​Ingest

​reportUsage

​reportEvent

​Batching usage reports

​Ingest fields

​Full check-then-ingest pattern

Check

By feature

By credit

Check request fields

Check response

Finding the binding constraint

Ingest

reportUsage

reportEvent

Batching usage reports

Ingest fields

Full check-then-ingest pattern