Usage, Billing & Credits

Usage reporting

The Stigg SDK allows you to report usage measurements for metered features. The reported usage is used to track, limit, and bill the customer’s usage of metered features.

Report usage only after the relevant resources have been provisioned in your application.
Ensure customers are not allowed to allocate new resources until an acknowledgement about the processed measurement is received from the Stigg backend.

Calculated usage

Report pre-aggregated usage values calculated by your application. This is useful for features like seats or storage. You provide the customer ID, the metered feature ID, and the usage value. Optionally, specify a resource ID and update behavior - by default the value represents the change in usage (delta), but you can also set the usage to an absolute value.

// increment usage of a metered feature by 10
await stiggClient.reportUsage({
  customerId: 'customer-test-id',
  featureId: 'feature-seats',
  value: 10,
  resourceId: 'resource-01',      // optional
});

Show Result (Node.js)

{
  "measurementId": "e7293df0-2d69-4713-9913-10ed06b9b777"
}

Synchronous credit balance updates

When the reported feature is credit-backed, reportUsage also returns a credit object in the response containing the updated credit balance — immediately, before the asynchronous metering pipeline completes. The deduction is applied optimistically (write-back cache strategy): the response reflects the balance as if the usage has already settled, and reconciliation to the exact source-of-truth value happens in the background. This makes reportUsage the right choice for strict, real-time credit enforcement (e.g., AI token consumption, per-call API billing), while reportEvent remains the choice for high-volume, eventually-consistent use cases.

	`reportUsage`	`reportEvent`
Latency	Sub-second	~10 seconds
Credit balance in response	Yes — optimistic, immediate	No
Volume	Lower	Higher
Best for	Strict enforcement, real-time UX	High-volume metering, less strict enforcement

Show Result — credit-backed feature (Node.js)

{
  "measurementId": "e7293df0-2d69-4713-9913-10ed06b9b777",
  "credit": {
    "currencyId": "currency-tokens",
    "currentUsage": 3500,
    "usageLimit": 10000,
    "timestamp": "2026-06-23T12:01:45.000Z"
  }
}

currentUsage is the total credits consumed so far. usageLimit is the total granted. Remaining balance = usageLimit - currentUsage.

Calculated usage can also be reported in bulk.

Raw events

Report raw events from your application, which Stigg filters and aggregates to calculate customer usage. This is useful for features like monthly active users (MAUs). You provide the customer ID, event name, and an idempotency key for deduplication. Optionally, include dimensions (key-value pairs for filtering and aggregation), a resource ID, and a timestamp.

await stiggClient.reportEvent({
  customerId: 'customer-test-id',
  resourceId: 'resource-01',      // optional
  eventName: 'user_login',
  idempotencyKey: '227c1b73-883a-457b-b715-6ba5a2c69ce4',
  dimensions: {
    user_id: 'user-01',
    user_email: 'john@example.com'
    },
  timestamp: '2022-10-26T15:01:55.768Z' // optional
});

Events can also be sent in batches.

Metering and aggregation capabilities

Paywall data

Retrieve paywall data for rendering a public pricing page or customer-facing paywall. Returns plans with their entitlements, pricing, trial configurations, compatible add-ons, and product metadata.

const paywallData = await stiggClient.getPaywall();

Cost estimation

Estimating new subscription cost

Estimate the cost of a new subscription before the customer commits. Useful for displaying pricing previews.

await stiggClient.estimateSubscription({
  customerId: "customer-demo-01",
  billingPeriod: "MONTHLY",
  planId: "plan-revvenu-growth",
  billableFeatures: [{ 						// optional, required for per-unit pricing
    featureId:'feature-01-templates',
    quantity: 2
  }],
  addons: [{  								// optional
  	addonId: 'addon-10-campaigns',
    quantity: 1
  }],
  promotionCode: "STIGG50",		// optional
  startDate: new Date(), 			// optional
  billingCountryCode: 'US', 	// optional, required for price localization
  resourceId: 'resource-01',  // optional, required for multiple subscriptions
});

The response includes a cost breakdown (total, subtotal, tax), applied discount details (type, value, duration), the billing period date range, and prorated credit/debit amounts.

Show Result (Node.js)

{
  "total": {
    "amount": 10,
    "currency": "USD"
  },
  "subTotal": {
    "amount": 10,
    "currency": "USD"
  },
  "billingPeriodRange": {
    "start": "2022-10-26T00:00:00.000Z",
    "end": "2022-11-26T00:00:00.000Z"
  },
  "discount": {
    "type": "PERCENTAGE",
    "value": 50,
    "durationType": "REPEATING",
    "durationInMonths": 3
  },
  "proration": {
    "credit": {
      "amount": 0,
      "currency": "USD"
    },
    "debit": {
      "amount": 10,
      "currency": "USD"
    },
    "netAmount": {
      "amount": 10,
      "currency": "USD"
    },
    "prorationDate": "2022-10-26T00:00:00.000Z"
  }
}

Estimating subscription update cost

Estimate the cost of updating an existing subscription (e.g., changing seat count or add-ons), including a proration breakdown.

Promo code support requires an integration with a billing solution such as Stripe. Promo codes must be generated in the integrated billing solution.

await stiggClient.estimateSubscriptionUpdate({
  subscriptionId: "subscription-plan-revvenu-growth-da6324",
  billableFeatures: [{ // optional
    featureId: 'feature-01-templates',
    quantity: 3
  }],
  addons: [{ // optional
    addonId: 'addon-10-campaigns',
    quantity: 1
  }],
  promotionCode: "STIGG50" // optional
});

Promotional entitlements

Granting promotional entitlements

Grant time-limited or custom-period promotional entitlements to customers, with optional usage limits and reset periods.

// Use the grantPromotionalEntitlements method — see the Node.js SDK reference for full usage:
// https://node-sdk-docs.stigg.io/classes/stigg#grantpromotionalentitlements

Revoking promotional entitlements

Revoke previously granted promotional entitlements from a customer.

// Use the revokePromotionalEntitlements method — see the Node.js SDK reference for full usage:
// https://node-sdk-docs.stigg.io/classes/stigg#revokepromotionalentitlements

Coupons

Retrieve available coupons, including their discount values, types, and metadata.

const coupons = await stiggClient.getCoupons();

Credits

Grant credits

Grant credits to a customer’s credit pool. Set grantType to PAID for purchased credits or PROMOTIONAL for free or incentive credits. Pass resourceId to credit a resource-specific pool rather than the global pool.

await stiggClient.createCreditGrant({
  customerId: 'customer-demo-01',
  currencyId: 'ai-tokens',
  displayName: 'Onboarding bonus',
  amount: 1000,
  grantType: 'PROMOTIONAL',
  resourceId: 'workspace-example-com', // optional — scope to a resource pool
  effectiveAt: new Date(),             // optional
  expireAt: new Date('2026-12-31'),    // optional
  comment: 'Welcome promotion',        // optional
});

Void credit grant

Cancel an active credit grant by its ID. Any remaining credits in the grant are immediately removed from the customer’s balance.

await stiggClient.voidCreditGrant({ id: 'grant-abc123' });

Query credit usage

Retrieve a customer’s credit consumption history as a time-series. Use timeRange for preset windows or startDate/endDate for an exact range. Break down consumption by any dimension key from your usage events using groupBy (up to 3 keys). Pass resourceId to scope the query to a specific resource pool.

// By preset time range
const usage = await stiggClient.getCreditUsage({
  customerId: 'customer-demo-01',
  currencyId: 'ai-tokens',         // optional — defaults to first active currency
  timeRange: 'LAST_MONTH',         // LAST_DAY | LAST_WEEK | LAST_MONTH | LAST_YEAR
  resourceId: 'workspace-example-com', // optional
});

// By exact date range, broken down by model dimension
const usageByModel = await stiggClient.getCreditUsage({
  customerId: 'customer-demo-01',
  startDate: new Date('2026-05-01'),
  endDate: new Date('2026-05-31'),
  groupBy: ['model'],              // any dimension key from your usage events
});

Show Response (Node.js)

{
  "series": [
    {
      "featureId": "feature-ai-tokens",
      "featureName": "AI Tokens",
      "totalCredits": 8420,
      "points": [
        { "timestamp": "2026-05-01T00:00:00Z", "value": 350 },
        { "timestamp": "2026-05-02T00:00:00Z", "value": 480 }
      ]
    }
  ],
  "currency": { "currencyId": "ai-tokens", "displayName": "AI Tokens" },
  "pageInfo": { "hasNextPage": false, "hasPreviousPage": false }
}

When groupBy is set, each series entry includes a tags array instead of featureId/featureName:

{
  "series": [
    {
      "featureId": null,
      "featureName": null,
      "totalCredits": 16922285,
      "tags": [{ "key": "model", "value": "gemini" }],
      "points": [...]
    }
  ]
}

Query credit ledger

Retrieve the append-only ledger of all credit events for a customer — grants, deductions, expirations, and revocations in chronological order. Pass resourceId to scope to a resource-specific pool.

const ledger = await stiggClient.getCreditLedger({
  customerId: 'customer-demo-01',
  currencyId: 'ai-tokens',              // optional
  resourceId: 'workspace-example-com', // optional
  paging: { first: 50 },              // optional
});

Query credit grants

List all credit grants for a customer, with optional filtering by resource and currency.

const grants = await stiggClient.getCreditGrants({
  customerId: 'customer-demo-01',
  currencyId: 'ai-tokens',              // optional
  resourceId: 'workspace-example-com', // optional
  paging: { first: 20 },              // optional
});

List available dimension keys

Retrieve the dimension keys that exist on a customer’s credit usage events. Use search to filter by keyword. This powers the searchable Group by dropdown in analytics UIs.

const fields = await stiggClient.getCreditEventsFields({
  customerId: 'customer-demo-01',
  currencyId: 'ai-tokens', // optional
  search: 'model',         // optional — filter keys by substring
});
// → { fields: ['model', 'model_version'] }

Credit auto-recharge

Configure automatic credit recharge for customers. When a customer’s credit balance drops below thresholdValue, Stigg automatically tops up to targetBalance. Set isEnabled: false to disable recharge without losing the configuration.

await stiggClient.saveAutoRechargeSettings({
  customerId: 'customer-demo-01',
  currencyId: 'ai-tokens',
  isEnabled: true,
  thresholdType: 'CREDIT_AMOUNT',  // CREDIT_AMOUNT | DOLLAR_AMOUNT
  thresholdValue: 500,             // trigger when balance drops below this
  targetBalance: 5000,             // top up to this amount
  maxSpendLimit: 100,              // optional — monthly USD spend cap
  grantExpirationPeriod: 'MONTH',  // optional — expiry for auto-granted credits
});

Usage reporting

Calculated usage

Synchronous credit balance updates

Raw events

Metering and aggregation capabilities

Paywall data

Cost estimation

Estimating new subscription cost

Estimating subscription update cost

Promotional entitlements

Granting promotional entitlements

Revoking promotional entitlements

Coupons

Credits

Grant credits

Void credit grant

Query credit usage

Query credit ledger

Query credit grants

List available dimension keys

Credit auto-recharge

Auto-recharge overview

​Usage reporting

​Calculated usage

​Synchronous credit balance updates

​Raw events

Metering and aggregation capabilities

​Paywall data

​Cost estimation

​Estimating new subscription cost

​Estimating subscription update cost

​Promotional entitlements

​Granting promotional entitlements

​Revoking promotional entitlements

​Coupons

​Credits

​Grant credits

​Void credit grant

​Query credit usage

​Query credit ledger

​Query credit grants

​List available dimension keys

​Credit auto-recharge

Auto-recharge overview

Usage reporting

Calculated usage

Synchronous credit balance updates

Raw events

Paywall data

Cost estimation

Estimating new subscription cost

Estimating subscription update cost

Promotional entitlements

Granting promotional entitlements

Revoking promotional entitlements

Coupons

Credits

Grant credits

Void credit grant

Query credit usage

Query credit ledger

Query credit grants

List available dimension keys

Credit auto-recharge