Backend Integration - Stigg Documentation

Stigg provides backend SDKs and APIs that allow you to manage customers, subscriptions, entitlements, and usage reporting from your server-side application.

For the Sidecar SDK (gRPC-based, optimized for low-latency entitlement checks), see the dedicated Sidecar SDK page.

Authentication

All backend SDKs authenticate using the Full access key, which can be found in the Stigg app under Integrations > API keys.

The Full access key should only be used in server-side applications and should never be exposed in client-side code.

Installing the SDK

npm install @stigg/node-server-sdk

SDK initialization

All SDKs are initialized with the Full access key. The SDK instance should be initialized once per process (singleton pattern) and reused throughout your application, as it maintains an internal cache and supports retries.

import { Stigg } from '@stigg/node-server-sdk';

const stiggClient = Stigg.initialize({ apiKey: 'YOUR_FULL_ACCESS_KEY' });

export default stiggClient;

Customer management

Provisioning customers

When a new customer is provisioned in your application (for example, during registration or onboarding), you should also provision them in Stigg. You provide the customer’s unique identifier, and optionally their name, billing email address, a coupon to apply, initial subscription parameters, billing and shipping addresses (including tax IDs and payment method), and arbitrary metadata.

To control the customer’s initial access to a product according to the product’s Customer Journey settings, initial subscription parameters must be provided. To provision a customer without any default subscription, explicitly pass no subscription parameters.

Passing billing information will cause the customer to be synced to the integrated billing solution even if they don’t have any paid subscriptions. Billing information is not persisted on Stigg’s servers.

const customer = await stiggClient.provisionCustomer({
    customerId: 'customer-test-id',
    name: 'My very first customer', // optional
    email: 'john@example.com',      // optional - billing email address
    couponId: 'coupon-test-id',     // optional
    subscriptionParams: {           // optional - pass null to skip initial subscription
      planId: 'plan-basic',
      resourceId: 'resource-01',      // optional, required for multiple subscription for same product
      billableFeatures: [{ 						// optional, required for subscriptions with per unit pricing
        featureId:'feature-01-templates',
        quantity: 2
      }],
      billingPeriod: 'MONTHLY', 			// optional, relevant only for paid subscriptions
      addons: [{  										// optional
        addonId: 'addon-extra-stuff',
        quantity: 1,
      }],
      promotionCode: 'STIGG30', 			// optional
      billingCountryCode:'DK',     		// optional, required for price localization, must be in the ISO-3166-1 format
      metadata: { 									  // optional
        key: 'value',
      },
    },
    metadata: { 				// optional - metadata that will be stored in Stigg
        key: "value",
    }
});

Show Result (Node.js)

{
  "customer": {
    "id": "customer-test-id",
    "experimentInfo": {
      "name": "should we use freemium?",
      "id": "should-we-use-freemium",
      "groupName": "Variant group",
      "groupType": "VARIANT"
    }
  },
  "subscriptionDecisionStrategy": "REQUESTED_PLAN",
  "subscription": {
    "id": "subscription-plan-basic-ed5dac",
    "planId": "plan-basic",
    "status": "ACTIVE",
    "addons": [],
    "customerId": "customer-test-id",
    "pricingType": "FREE",
    "resource": {
      "id": "resource-01"
    }
  }
}

Updating customers

Customer information can be updated at any time. Only the fields being updated need to be sent.

Since billing information is not persisted on Stigg’s servers, the entire billing information object must be passed each time it needs to be updated.

const customer = await stiggClient.updateCustomer({
    customerId: 'customer-test-id',
    email: 'john@example.com', // optional, use to update the customer's email address
    couponId: 'coupon-test-id',   // optional, use to apply a coupon to a customer
    billingInfo: {  							// optional, use to update the customer's billing information
        ...
    },
    metadata: {  									// optional, use to update the customer's metadata
      key: 'value',
    }
});

Show Result (Node.js)

{
  "id": "customer-test-id"
}

Getting customer data

Retrieve customer details by their customer ID, including metadata, promotional entitlements, and payment method status.

const customer = await stiggClient.getCustomer('customer-demo-01');

Show Result (Node.js)

{
  "id": "customer-demo-01",
  "name": "Test Name",
  "email": "john@example.com",
  "createdAt": "2022-09-20T09:59:22.324Z",
  "updatedAt": "2022-09-20T10:00:32.750Z",
  "hasPaymentMethod": false,
  "promotionalEntitlements": [],
  "metadata": {
    "lorem": "ipsum"
  }
}

Archiving customers

When a customer is archived:

Their PII (name and email) will be nullified.
They will no longer appear in the Stigg app UI.
They will no longer be returned by the Stigg API and SDKs.

New customers cannot reuse the customer ID of archived customers. When Stigg is integrated with a billing solution, archived customers will still exist in the billing solution to allow upcoming invoices to be finalized.

Subscription management

Provisioning subscriptions

When a customer subscribes to a new plan (upgrade, downgrade, or initial subscription), a subscription needs to be provisioned in Stigg. You provide the customer ID and target plan ID. For paid subscriptions, the billing period (monthly or annually) is required. Additional optional parameters include:

Resource ID - required when a product supports multiple active subscriptions
Billable feature quantities - required for per-unit pricing
Add-ons - list of add-ons and their quantities
Promotion code - a promo code from your billing provider
Billing country code - ISO-3166-1 format, required for price localization
Checkout options - configuration for hosted checkout (success/cancel URLs, promo code collection, etc.)
Metadata - arbitrary key-value pairs

Behavior:

When payment details are required and not yet provided, Stigg redirects the customer to the billing solution’s hosted checkout page.
When no payment is required, the subscription is created immediately.
The result includes the subscription details or a checkout URL if payment is needed.

const subscription = await stiggClient.provisionSubscription({
    customerId: 'customer-demo-01',
    planId: 'plan-basic',
    billingPeriod: 'MONTHLY',                   // optional, required for paid subscriptions
    resourceId: 'resource-01',                  // optional, required for multiple subscriptions
    billableFeatures: [{
      featureId:'feature-01-templates',
      quantity: 2
    }],
    addons: [{
        addonId: 'addon-extra-stuff',
        quantity: 1,
    }],
    promotionCode: 'STIGG30', 		              // optional
    billingCountryCode:'DK',     		            // optional, required for price localization
    checkoutOptions: {                          // optional
      successUrl: "https://your-success-url.com",
      cancelUrl: "https://your-cancel-url.com",
      allowPromoCodes: true,
      collectBillingAddress: true,
    },
    metadata: {
      key: 'value',
    }
});

Show Result (Node.js)

{
  "status": "Success",
  "checkoutUrl": "https://your-success-url.com",
  "subscription": {
    "id": "subscription-plan-basic",
    "planId": "plan-basic",
    "status": "ACTIVE",
    "addons": [],
    "customerId": "customer-demo-01",
    "resource": {
      "id": "resource-01"
    },
    "metadata": {
      "lorem": "ipsum"
    },
    "pricingType": "FREE",
    "paymentCollection": "NOT_REQUIRED",
    "latestInvoice": {
      "billingId": "invoice-01",
      "status": "PAID"
    }
  }
}

A customer can have both a non-trial and a trial subscription to different plans of the same product in parallel.
When a customer with a trial subscription for plan X creates a new subscription for the same plan, it will be created as a non-trial (paid) subscription.
When a customer already has an active subscription for a product and a new one is created, the existing subscription is automatically cancelled.
You can explicitly skip the trial period by providing a skip-trial flag.

Updating subscriptions

Update an existing subscription without creating a new one, keeping the original start date and billing cycle. You can:

Update subscription metadata
Update unit quantity for per-unit pricing (e.g., adding or removing seats)
Add or remove add-ons (only if compatible with the plan)
Update the promotion code
Update the billing period

When integrated with a billing solution, modifying quantities or add-ons generates a prorated invoice.

const subscription = await stiggClient.updateSubscription({
  subscriptionId: 'subscription-plan-basic',
  billableFeatures: [{
    featureId:'feature-01-templates',
    quantity: 3
  }],
  promotionCode: "STIGG30", // optional
  addons: [
    { addonId: 'extra-api-calls', quantity: 5 }
  ],
  metadata: {
      key: 'newValue'
  },
});

Show Result (Node.js)

{
  "id": "subscription-plan-basic",
  "planId": "plan-basic",
  "status": "ACTIVE",
  "addons": [],
  "customerId": "customer-demo-01",
  "resource": {
    "id": "resource-01"
  },
  "metadata": {
    "key": "newValue"
  },
  "pricingType": "FREE"
}

Canceling subscriptions

Cancel a subscription by its ID. Cancellation behavior (immediate or end of billing period) is determined by the product’s configuration.

await stiggClient.cancelSubscription({
    subscriptionId: 'subscription-plan-basic'
});

Show Result (Node.js)

{
  "id": "subscription-plan-basic",
  "planId": "plan-basic",
  "status": "CANCELED",
  "customerId": "customer-demo-01",
  "metadata": {
    "key": "newValue"
  },
  "pricingType": "FREE",
  "effectiveEndDate": "2022-09-20T10:18:06.842Z"
}

Canceling scheduled updates

Cancel all scheduled updates or pending payment updates for a given subscription.

Listing active subscriptions

Retrieve a list of a customer’s active subscriptions. For products that support multiple active subscriptions, pass one or more resource IDs to filter by resource.

Getting a specific subscription

Retrieve extended details for a single subscription, including plan details, add-ons, pricing, payment collection status, and the latest invoice.

Listing subscriptions with filtering

Query subscriptions with rich filtering, sorting, and cursor-based pagination. Useful for admin dashboards, audits, and reporting. Supported filter operators include equality, inequality, inclusion, and exclusion for strings and enums, as well as comparison operators for dates. Filters support logical AND/OR composition. Sortable fields include creation date, customer ID, environment ID, product ID, resource ID, and status.

Entitlement checks

Stigg supports three types of feature entitlements: boolean (on/off), numeric (configuration values), and metered (usage-tracked with limits).

Generic entitlement check (recommended)

A unified method to check any type of feature entitlement. It automatically returns the appropriate entitlement type based on the feature configuration. You provide the customer ID and feature ID. Optionally, pass a resource ID for multi-subscription products, or a requested usage amount to proactively check if additional usage would be allowed (metered features only).

const entitlement = await stiggClient.getEntitlement({
  customerId: 'customer-demo-01',
  featureId: 'feature-demo-01',
  resourceId: 'resource-01', // optional, pass it to get entitlement of specific resource
});

if (entitlement.hasAccess) {
  // Customer has access to the feature
} else {
  // Access denied
  console.log('Access denied reason:', entitlement.accessDeniedReason);
}

// Entitlement contains the specific entitlement details
// based on feature type (boolean, numeric, or metered)
switch (entitlement.type) {
  case "NUMERIC":
    console.log('Numeric value:', entitlement.value);
    break;
  case "METERED":
    console.log('Usage limit:', entitlement.usageLimit);
    console.log('Current usage:', entitlement.currentUsage);
    break;
  case "BOOLEAN":
    break;
}

Show Result - boolean feature

{
  "isFallback": false,
  "hasAccess": true,
  "entitlement": {
    "type": "BOOLEAN",
    "feature": {
        "id": "feature-demo-01",
        "featureType": "Boolean",
        "meterType": "None",
        "isMetered": false
    }
  }
}

Show Result - numeric feature

{
  "isFallback": false,
  "hasAccess": true,
  "entitlement": {
    "type": "NUMERIC",
    "feature": {
      "id": "feature-demo-02",
      "featureType": "Numeric",
      "units": "request",
      "unitsPlural": "requests",
      "isMetered": false
    },
    "value": 100,
    "isUnlimited": false
  }
}

Show Result - metered feature

{
  "isFallback": false,
  "hasAccess": true,
  "entitlement": {
    "type": "METERED",
    "feature": {
      "id": "feature-demo-03",
      "featureType": "Numeric",
      "meterType": "Incremental",
      "units": "request",
      "unitsPlural": "requests",
      "isMetered": true
    },
    "usageLimit": 2,
    "isUnlimited": false,
    "currentUsage": 0,
    "resetPeriod": "MONTH"
  }
}

Boolean entitlement check

Check whether a customer has access to a boolean (on/off) feature.

const entitlement = await stiggClient.getBooleanEntitlement({
  customerId: 'customer-demo-01',
  featureId: 'feature-demo-01',
  resourceId: 'resource-01',      // optional
});

if (entitlement.hasAccess) {
  // customer has access to the feature
} else {
  // access denied
}

Numeric entitlement check

Retrieve the numeric value configured for a feature (e.g., max file size, API rate limit).

const entitlement = await stiggClient.getNumericEntitlement({
  customerId: 'customer-demo-01',
  featureId: 'feature-demo-02',
  resourceId: 'resource-01',      // optional
});

if (entitlement.hasAccess) {
  console.log(entitlement.value);
}

Metered entitlement check

Check whether a customer’s usage of a metered feature is within the allowed quota. You can optionally provide a requested usage amount to proactively verify if a specific amount of additional usage would be allowed before performing the action.

const entitlement = await stiggClient.getMeteredEntitlement({
  customerId: 'customer-demo-01',
  featureId: 'feature-demo-03',
  resourceId: 'resource-01',      // optional
  options: {
    requestedUsage: 10             // optional, proactively check usage
  },
});

if (entitlement.hasAccess) {
  // has access and the requested usage is within the allowed quota
} else {
  // the customer has exceeded his quota for this feature
}

Getting all entitlements

Retrieve all entitlements for a customer (or a specific resource), returning the full list of features they have access to along with usage limits and current usage.

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

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.

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.

Promotional entitlements

Granting promotional entitlements

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

Revoking promotional entitlements

Revoke previously granted promotional entitlements from a customer.

Coupons

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

Products

Retrieve all products configured in Stigg, including display names, descriptions, metadata, and downgrade plan information.

Real-time updates

The Node.js Server SDK supports a streaming connection to receive real-time updates with low latency when customer entitlements or usage change. Available events:

Entitlements updated - fired when a customer’s entitlements change
Usage updated - fired when a customer’s usage is updated

Subscription migration

Migrate subscriptions to the latest plan and add-on version on a subscription-by-subscription basis, to prevent SKU sprawl from grandfathering.

When the current subscription price differs from the latest published version, the customer will be charged or credited the prorated difference.

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.

Advanced features

Persistent caching

Configure a persistent cache (Redis) to survive restarts and share cache across multiple instances.

Persistent caching

Offline mode

The Node.js Server SDK supports offline mode for local development and testing, avoiding network requests to the Stigg API. In offline mode, entitlement evaluations use fallback values. The Sidecar SDK (Java) supports an offline/air-gapped mode for environments with restricted network access, enabling in-memory entitlement evaluation without connecting to a Sidecar process.

Sidecar service

The Sidecar service provides low-latency entitlement checks, handles caching, and subscribes to real-time entitlement and usage data updates. It can be deployed as a sidecar container or a standalone service.

Sidecar service

SDK references

Node.js SDK

Full reference for the Node.js Server SDK

Python SDK

Full reference for the Python API client

Go SDK

Full reference for the Go API client

GraphQL API

Interactive GraphQL API playground

SDK changelogs

Node.js

Node.js SDK changelog

Python

Python SDK changelog

Ruby

Ruby SDK changelog

Go

Go SDK changelog

Java

Java SDK changelog

.NET

.NET SDK changelog

Sidecar

Sidecar SDK changelog

Integration guides

Quick start guides

I want to...

​Authentication

​Installing the SDK

​SDK initialization

​Customer management

​Provisioning customers

​Updating customers

​Getting customer data

​Archiving customers

​Subscription management

​Provisioning subscriptions

​Updating subscriptions

​Canceling subscriptions

​Canceling scheduled updates

​Listing active subscriptions

​Getting a specific subscription

​Listing subscriptions with filtering

​Entitlement checks

​Generic entitlement check (recommended)

​Boolean entitlement check

​Numeric entitlement check

​Metered entitlement check

​Getting all entitlements

​Usage reporting

​Calculated usage

​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

​Products

​Real-time updates

​Subscription migration

​Credit auto-recharge

​Advanced features

​Persistent caching

Persistent caching

​Offline mode

​Sidecar service

Sidecar service

​SDK references

Node.js SDK

Python SDK

Go SDK

GraphQL API

​SDK changelogs

Node.js

Python

Ruby

Go

Java

.NET

Sidecar

Authentication

Installing the SDK

SDK initialization

Customer management

Provisioning customers

Updating customers

Getting customer data

Archiving customers

Subscription management

Provisioning subscriptions

Updating subscriptions

Canceling subscriptions

Canceling scheduled updates

Listing active subscriptions

Getting a specific subscription

Listing subscriptions with filtering

Entitlement checks

Generic entitlement check (recommended)

Boolean entitlement check

Numeric entitlement check

Metered entitlement check

Getting all entitlements

Usage reporting

Calculated usage

Raw events

Paywall data

Cost estimation

Estimating new subscription cost

Estimating subscription update cost

Promotional entitlements

Granting promotional entitlements

Revoking promotional entitlements

Coupons

Products

Real-time updates

Subscription migration

Credit auto-recharge

Advanced features

Persistent caching

Offline mode

Sidecar service

SDK references

SDK changelogs