Usage, billing & credits

Report usage, estimate costs, manage credits, promotions, and coupons using Stigg backend SDKs.

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.

1. Report usage only after the relevant resources have been provisioned in your application.
2. 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.

Node.js

// 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"
}

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.

Node.js

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: '[e-mail]'
    },
  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.

Node.js

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.

Node.js

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.

Node.js

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.

Node.js

// 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.

Node.js

// 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.

Node.js

const coupons = await stiggClient.getCoupons();

Credit auto-recharge

Configure automatic credit recharge for customers. When a customer’s credit balance drops below a configured threshold, Stigg automatically tops up their balance.

Configuration includes the threshold type (credit amount or dollar amount), threshold value, target balance to recharge to, an optional maximum monthly spend limit, and an expiration period for granted credits.