Estimate usage credit cost

Estimates the credit cost of a usage report without recording it. Returns the estimated cost per credit currency, the current balance, and the balance after the estimated consumption.

POST /api/v1/usage/estimate

JavaScript

JavaScript

import Stigg from '@stigg/typescript';

const client = new Stigg({
  apiKey: process.env['STIGG_API_KEY'], // This is the default and can be omitted
});

const response = await client.v1.usage.estimate({
  customerId: 'customerId',
  featureId: 'featureId',
  value: -9007199254740991,
});

console.log(response.data);

200

{
  "data": {
    "estimates": [
      {
        "currencyId": "<string>",
        "estimatedCost": 123,
        "currentBalance": 123,
        "balanceAfterEstimate": 123,
        "wouldOverdraft": true,
        "breakdown": [
          {
            "featureId": "<string>",
            "cost": 123,
            "warningCode": "UNSUPPORTED_AGGREGATION"
          }
        ]
      }
    ],
    "warnings": [
      "RESOURCE_SCOPED_SUBSCRIPTION_EXISTS"
    ]
  }
}

Authorizations

X-API-KEY · string · header · required

Server API Key

Headers

X-ACCOUNT-ID · string

Account ID — optional when authenticating with a user JWT (Bearer token); falls back to the user's first membership. Ignored for API-key auth.

X-ENVIRONMENT-ID · string

Environment ID — required when authenticating with a user JWT (Bearer token) on environment-scoped endpoints. Ignored for API-key auth (env is intrinsic to the key).

Body

application/json

Estimate the credit cost of a usage report before reporting it

value · integer · required

The value to report for usage. Must be a whole number — the REST API does not accept fractional (float) usage values; scale up (e.g. report cents instead of dollars, or milliseconds instead of seconds) if you need sub-unit precision.

Required range: x >= -9007199254740991

featureId · string · required

Feature id

Required string length: 1 - 255

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$

customerId · string · required

Customer id

Required string length: 1 - 255

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.@-]*$

resourceId · string | null

The customer resource this usage applies to. Optional — only required if the customer has multiple resources (for example, one subscription per workspace or site) and usage needs to be tracked separately per resource; omit it to report usage at the customer level.

Required string length: 1 - 255

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$

updateBehavior · enum<string> · default: DELTA

How the reported value is applied: DELTA (default) adds it to the feature's current usage; SET treats it as the new absolute usage total, and Stigg computes the delta internally.

Available options: DELTA, SET

dimensions · object

Additional dimensions for the usage report

Show child attributes

Response

200

application/json

The credit cost estimation, including per-currency costs, balances, and warnings.

Response object

data · CreditCostEstimation · object · required

Estimated credit cost, current balance and balance after

Show child attributes