Skip to main content

​
Overview

When calculated usage is reported to Stigg, your application is responsible for aggregating and calculating the usage and then reporting it to Stigg.

​
Supported ingestion behaviors

Stigg supports 2 behaviors for reporting calculated usage:
  1. Delta - the reported usage represents the change in usage of the feature, for example: when a customer adds 2 more seats, the reported value should be 2. This is default behavior.
  2. Set - the reported usage represents the end state after the change, for example: when a customer adds 2 more seats and the total number of seats after the change is 5, the reported value should be 5.
It is also possible to report usage in bulk using the Report Usage Bulk endpoint in batches of 100 measurements (GraphQL SDK only; note the rate limit for this operation)

​
Idempotency

Reporting usage over the network means requests can occasionally be retried, for example: after a timeout, a dropped connection, or a client-side retry policy. To make retries safe, you can pass an optional idempotencyKey alongside a reported usage value. A retry with a previously-seen idempotency key is deduplicated rather than counted as new usage. Idempotency keys shouldn’t be reused across unrelated reports.
Since calculated usage typically represents a delta (for example: “add 2 seats”), a duplicate that isn’t deduplicated is applied again and silently inflates the customer’s usage. Always pass an idempotencyKey when there’s a chance a report could be retried, such as usage reported from a background job or in response to a webhook.

​
Choosing an idempotency key

Prefer a key that’s deterministic — derived from the source data that triggered the report (for example: {customerId}-{featureId}-{sourceEventId}) rather than a random UUID generated fresh on every attempt. A deterministic key means any retry of the same underlying action, from any code path (a manual retry, a queue redelivery, a cron re-run), naturally reuses the same key and gets deduplicated, instead of relying on a single caller to remember and resend the exact key it used the first time.

​
Handling errors and retries

​
Supported ingestion methods

REST SDKs

Send usage data using REST SDKs available for TypeScript, Python, Go, Ruby, C#, and Java.

REST API: Report Usage

Send calculated usage values via the REST API.

​
Example use-case

​
Seats

When a customer invites additional users to their environment, report the number of new seats that were added to Stigg. Similarly, when a customer removes users from their environment report the number of seats that were removed from the environment to Stigg.

​
Bandwidth

Periodically query the infrastructure that tracks used bandwidth (for example: AWS CloudWatch) and report the calculated usage to Stigg.