Backend

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

​

Authentication

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

​

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.

• For the Node.js Server SDK, you can await initialization to ensure the client is ready before use, and configure options like offline mode and fallback entitlements.
• For the Sidecar SDK, initialization also requires the host and port of the Sidecar service.

​

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.

​

Updating customers

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

​

Getting customer data

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

​

Archiving customers

When a customer is archived:

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

​

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.

​

Updating subscriptions

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

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

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

​

Canceling subscriptions

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

​

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). The response indicates whether the customer has access, the reason for denial (if applicable), whether the result is from fallback data, and entitlement-specific details based on the feature type (boolean, numeric value, or usage limits and current usage).

​

Boolean entitlement check

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

​

Numeric entitlement check

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

​

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.

​

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.

​

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

​

Estimating subscription update cost

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

​

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.

​

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

​

SDK changelogs