Installing the SDK

The first step is to install the Stigg SDK as a dependency in your application using your application’s dependency manager:

npm install @stigg/node-server-sdk

Retrieving the server API Key

In the Stigg app, go to Settings > Account > Environments. Copy the Server API key of the relevant environment.

Initializing the SDK

Import the Stigg client and initialize it with the API key:

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

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

export default stiggClient;

The Stigg SDK instance has an internal cache and supports retries for certain API calls on network errors. In general, you should initialize it once per process (for example: using a singleton design-pattern) and use the same instance throughout the codebase.

To find out when the client is ready, you can use waitForInitialization which return a promise that resolves when the client is ready to use, or rejects when the initialization failed.

try {
  await stiggClient.waitForInitialization();
  // initialization succeeded, entitlements values are now available
} catch (err) {
  // initialization failed
}

Provisioning customers

When a new customer is provisioned within your application (for example: as part of your registration or onboarding process), you should also provision them in Stigg. You can optionally pass subscriptionParams to create a subscription for that customer using a single operation. The actual subscription that is created for the customer can be overriden by Stigg admin from the Stigg Console, according to the product’s Customer Journey settings.

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',  
      },
      billingInformation: {
        taxPercentage: 17,// optional. taxRate will be created if not exists
      }
    },
    billingInfo: {                  // optional
        language: 'en',  
        timezone: 'America/New_York',
        customerName: "The name of the customer for the billing provider",
        billingAddress: {  
          country: 'US',  				// must be in the ISO-3166-1 format
          city: 'New York',  
          state: 'NY',  
          addressLine1: '123 Main Street',  
          addressLine2: 'Apt. 1',  
          phoneNumber: '+1 212-499-5321',  
          postalCode: '10164',  
        },  
        shippingAddress: {  
          country: 'US', 					// must be in the ISO-3166-1 format
          city: 'New York',  
          state: 'NY',  
          addressLine1: '123 Main Street',  
          addressLine2: 'Apt. 1',  
          phoneNumber: '+1 212-499-5321',  
          postalCode: '10164',  
        },  
        taxIds: [  
          { type: "au_abn", value: "12345678912" },  
          { type: "us_ein", value: "12-3456789" }  
        ],  
        invoiceCustomFields: {  
          lorem: "ipsum",  
          acme: "co"  
        },  
        paymentMethodId: "pm_1LcBMDAnAO1PFouUusJSmaPu",  
        currency: "usd",
      	metadata: { 		// optional - metadata that will be stored in the billing solution
          hello: "world"
        }
    },  
    metadata: { 				// optional - metadata that will be stored in Stigg
        key: "value",  
    }
});

Show Result

{
  "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": [],
    "addonIds": [],
    "customerId": "customer-test-id",
    "metadata": null,
    "price": null,
    "pricingType": "FREE",
    "resource": {
      "id": "resource-01",
    },
  }
}

In order to control customers’ initial access to the product according to product’s Customer Journey setting, the subscriptionParams must not be null.In order to provision a customer without any default subscription, simply pass subscriptionParams: null in the argument object.

The customer’s billing information can also be passed to the Stigg SDK when a customer is created or updated.When Stigg is integrated with additional service, this information will be propagated to the active integrations.Passing the billing information will cause the customer to be synced to the integrated billing solution even if it doesn’t have any subscriptions that are synced to the billing solution (i.e. free, trial, or custom).Customers’ billing information does not persist on Stigg’s servers.

Updating customers

Customer information can also be updated whenever you like assuming they already exists, for example: in order to update the customer’s email, you only need to send the new email value without the rest of the customer.

Due to the fact that the customer’s billing information is not persisted on Stigg’s servers, in order to update it the entire billingInfo objected must be passed each time.

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

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

Getting customer data

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

Show Result

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

Provisioning subscriptions

When a customer subscribes to a new plan (for example: during an upgrade from a free plan to a paid plan, or downgrade from a higher tier to a lower tier), a subscription needs to be provisioned in Stigg. When provisioning of a paid subscription is attempted, Stigg is integrated with a billing solution and payment details have not been previously provided by the customer, Stigg will auto-magically redirect customers to a the billing solution’s checkout page. After the customer enters the required payment details in the presented checkout page, the relevant subscription will be created in both Stigg and the billing solution. When no payment is required or when Stigg is not integrated with a billing solution, the subscription will be immediately created in Stigg. When a customer subscribes to a new plan (free, paid, trial, etc.), provision a subscription in Stigg. The provision result can be a successfully created subscription, or a redirect link to checkout page of the integrated billing solution in case payment details are required in order to complete the provisioning of the subscription.

const subscription = await stiggClient.provisionSubscription({  
    // Mandatory, subscription customer ID
    customerId: 'customer-demo-01',  
  
    // Mandatory, subscription plan ID
    planId: 'plan-basic',
  
    // Optional, required only for paid subscriptions  
    billingPeriod: 'MONTHLY',
    
    // Optional, required for multiple subscription for same product
    resourceId: 'resource-01',      

    // Optional, required for subscriptions with per unit pricing
    billableFeatures: [{ 						
      featureId:'feature-01-templates',
      quantity: 2
    }],
   	
    // Optional, list of subscription addons and quantities
    addons: [{  										
        addonId: 'addon-extra-stuff',  
        quantity: 1,  
    }],
    
    // Optional, used for discounts
    promotionCode: 'STIGG30', 		
  
    // Optional, required for price localization, must be in the ISO-3166-1 format
    billingCountryCode:'DK',     		
  
    // Optional
    billingInformation: {
      // Optional, list of tax rate IDs to apply in Stripe
      taxRateIds: [  
        "txr_1LcTSRE1gVT2zwZV07MIRKdf",  
        "txr_1LcTSRE1gVT2zwZV07MIRKdf"  
      ],
      
      // Optional, metadata that is being passed-through to the billing integration
      metadata: {
      	lorem: "ipsum"
      },
      
      // Optional, used to create a taxRate with the provided percent if not exists
      taxPercentage: 17,						
    },
  
    // Optional, parameters used for the hosted checkout
    checkoutOptions: {
      // Mandatory, redirect URL after the checkout is complete
      successUrl: "https://your-success-url.com",
      
      // Mandatory, redirect URL after the checkout is cancelled
    	cancelUrl: "https://your-cancel-url.com",
      
      // Optional, allow customer to use promo codes on checkout
      allowPromoCodes: true, 				
      
      // Optional, collect billing address for invoice on checkout
      collectBillingAddress: true, 	
      
      // Optional, pass an ID that can be used to reconcile the subscription with internal systems, such as referral programs
      referenceId: 'your-id-for-the-checkout-session', 
      
      // Optional, allow customer to insert taxId to be shown on the invoice
      allowTaxIdCollection: true, 	
      
      // Optional, collect phone number during checkout
      collectPhoneNumber: true
    },
    
    // Optional, can be used to store extra data
    metadata: {											
      key: 'value',  
    }
});

Show Success result

{
  "status": "Success",
  "checkoutUrl": "https://your-success-url.com",
  "subscription": {
    "id": "subscription-plan-basic",
    "planId": "plan-basic",
    "status": "ACTIVE",
    "addons": [
      
    ],
    "addonIds": [
      
    ],
    "customerId": "customer-demo-01",
    "resource": {
      "id": "resource-01",
    },
    "metadata": {
      "lorem": "ipsum"
    },
    "price": null,
    "pricingType": "FREE",
    "paymentCollection": "NOT_REQUIRED",
    "latestInvoice": {
      "billingId": "invoice-01",
      "status": "PAID",
    },
    "experimentInfo": {
      "name": "should we use freemium?",
      "id": "should-we-use-freemium",
      "groupName": "Variant group",
      "groupType": "VARIANT",    
    }
  }
}

Show Payment required action

{
  "status": "Success",
  "subscription": {
    "paymentCollectio"n: "ACTION_REQUIRED",
    "latestInvoice": {
      "paymentUrl": "https...",
      "paymentSecret": "secret"
    }
  }
}

Show Payment required failed

{
  "status": "Success",
  "subscription": {
    "paymentCollection": "FAILED",
    "latestInvoice": {
      "paymentUrl": "https...",
      "errorMessage": "no sufficient funds"
    }
  }
}

Show Payment required checkout

{
  "status": "PaymentRequired",
  "checkoutUrl": "https:///documentation/native-integrations/billing/stripe/integration-when-using-stripe-elements-for-checkout-checkout-page.com",
}

A customer can have both a non-trial (free or paid) subscription and trial subscription to different plans of the same product in parallel - this logic allows customers to trial a higher tier plan, while still paying for an existing plan.
When the customer has a trial subscription for plan X of product A and a new subscription is created for the same plan, the new subscription will be created as as non-trial (paid) subscription - this logic follows an upgrade flow of a trial subscription to a paid subscription of a specific plan.
Except in the above mentioned cases, when a customer has an active subscription for product X, and another subscription for the same product is created with start date S, the existing subscription will automatically be cancelled and the new subscription will start on start date S.
It’s also possible to explicitly skip the trial period of the selected plan by providing the skipTrial: true parameter to the provisionSubscription() method.

Passing of promo codes requires an integration with a billing solution, such as: Stripe.
Promo codes should be generated in the integrated billing solution.
When providing the optional promotionCode parameter, the promo code and associated coupon will validated against the defined restrictions to ensure that they’re applicable for the subscription. If validation fails, a relevant error code would be returned; otherwise, the subscription will include the discounted price.
When providing the optional promotionCode parameter and payment method is required, the promotion will be applied to the checkout session automatically.

This method replaces the createSubscription() method, which has been deprecated.

Updating subscriptions

It’s possible to update an existing subscription without creating a new one, keeping the original start date and billing cycle. Using this function you can:

Update subscription metadata
Update unit quantity, if the subscription has per-unit pricing (i.e. when customers add or removes a seat)
Add or remove add-ons, only if they are compatible with the subscription’s plan.
Update subscription promotion code.
Update subscription billing period

When integrated with a billing solution (for example: Stripe), whenever the unit quantity or add-ons are modified, a new invoice with prorated amount will be immediately generated in the integrated billing solution.

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'
  },
  billingInformation: {
    // Optional, metadata that is being passed-through to the billing integration
    metadata: {
      lorem: "ipsum"
    },
  },
  billingPeriod: BillingPeriod.Monthly
});

Show Result

{
  "id": "subscription-plan-basic",
  "planId": "plan-basic",
  "status": "ACTIVE",
  "addons": [],
  "addonIds": [],
  "customerId": "customer-demo-01",
  "resource": {
    "id": "resource-01",
  },
  "metadata": {
    "key": "newValue"
  },
  "price": null,
  "pricingType": "FREE",
  "experimentInfo": {
      "name": "should we use freemium?",
      "id": "should-we-use-freemium",
      "groupName": "Variant group",
      "groupType": "VARIANT",
  }
}

Passing of promo codes requires an integration with a billing solution, such as: Stripe.
Promo codes should be generated in the integrated billing solution.
When providing the optional promotionCode parameter, the promo code and associated coupon will validated against the defined restrictions to ensure that they’re applicable for the subscription. If validation fails, a relevant error code would be returned; otherwise, the subscription will include the discounted price.

Canceling subscriptions

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

Show Result

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

Subscription cancellation will take place according to the defined product behavior.

Canceling subscriptions scheduled updates

Will cancel all the scheduled updates of the given subscription

await stiggClient.cancelSubscriptionScheduledUpdates({  
  subscriptionId: 'subscription-plan-essentials',
  status: SubscriptionScheduleStatus.Scheduled,
});

Show Result

{
    "subscriptionId": "subscription-plan-essentials"
}

Canceling subscriptions pending payment updates

Will cancel all the pending payment updates of the given subscription

await stiggClient.cancelSubscriptionScheduledUpdates({  
  subscriptionId: 'subscription-plan-essentials',
  status: SubscriptionScheduleStatus.PendingPayment,
});

Show Result

{
    "subscriptionId": "subscription-plan-essentials"
}

Listing customers active subscriptions

The getActiveSubscriptionsList method returns a list of slim subscription data, for extended data of a specific subscription use getSubscription method.

Products with a single active subscription

To retrieve subscriptions for products that only allow customers to have a single active subscription:

const subscriptions = await stiggClient.getActiveSubscriptionsList({
  customerId: 'customer-demo-01',
});

Products with multiple active subscriptions

To retrieve subscriptions for products that allow customers to have multiple active subscriptions, include the resource ID of the relevant resource:

const subscriptions = await stiggClient.getActiveSubscriptionsList({
  customerId: 'customer-demo-01',
  resourceId: 'resource-01'
});

Passing more than one (and up to 100) resource ID will return the active subscriptions for all of the provided resources IDs.

const subscriptions = await stiggClient.getActiveSubscriptionsList({
  customerId: 'customer-demo-01',
  resourceId: ['resource-01', 'resource-02', 'resource-03' ]
});

Getting a specific subscription

To retrieve extended subscription:

const subscriptions = await stiggClient.getSubscription({
  subscriptionId: 'subscription-01',
});

Getting the entitlement of a customer to a specific feature

Generic entitlement check (recommended)

The getEntitlement method provides a unified way to check any type of feature entitlement. It automatically returns the appropriate entitlement type based on the feature configuration.

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":
    // Numeric feature - contains a value
    console.log('Numeric value:', entitlement.value);
    break;
  case "METERED":
    // Metered feature - contains usage and limits
    console.log('Usage limit:', entitlement.usageLimit);
    console.log('Current usage:', entitlement.currentUsage);
    console.log('Is unlimited:', entitlement.isUnlimited);
    break;
  case "BOOLEAN":
    // Boolean feature - no additional configuration
    break;
}

Show Result - boolean feature

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

Show Result - numeric feature

{
  "isFallback": false,
  "hasAccess": true,
  "entitlement": {
    type: "NUMERIC",
    "feature": {
      "id": "feature-demo-02",
      "featureType": "Numeric",
      "meterType": "None",
      "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",
    "usagePeriodAnchor": "2023-07-21T00:00:00Z",
    "usagePeriodStart": "2023-11-21T00:00:00Z",
    "usagePeriodEnd": "2023-12-21T00:00:00Z"
  }
}

The generic getEntitlement method is the recommended approach for checking feature entitlements as it provides a unified interface and automatically handles all entitlement types. For metered features, you can also pass a options.requestedUsage parameter to proactively check if additional usage would be allowed.

Checking the entitlement of a boolean feature

const entitlement = await stiggClient.getBooleanEntitlement({  
  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  
}

Show Result - has access

{
  "isFallback": false,
  "hasAccess": true,
  "feature": {
    "id": "feature-demo-01",
    "featureType": "Boolean",
    "meterType": "None",
    "units": "",
    "unitsPlural": "",
    "isMetered": false
  }
}

Show Result - no access

{
  "hasAccess": false,
  "accessDeniedReason": "CustomerNotEntitledForFeature",
  "isFallback": false
}

Checking the entitlement of a numeric configuration feature

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

if (entitlement.hasAccess) {  
  // get the entitlement numeric value that is defined for the feature  
  console.log(entitlement.value);  
}

Show Result - has access

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

Show Result - no access

{
  "hasAccess": false,
  "accessDeniedReason": "CustomerNotEntitledForFeature",
  "isFallback": false,
  "isUnlimited": false
}

Checking if a customer has access to a metered feature

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

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

Show Result - has access

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

Show Result - no access

{
  "isFallback": false,
  "hasAccess": false,
  "accessDeniedReason": "RequestedUsageExceedsLimit",
  "isUnlimited": false,
  "usageLimit": 2,
  "currentUsage": 0,
  "requestedUsage": 0,
  "feature": {
    "id": "feature-demo-03",
    "featureType": "Numeric",
    "meterType": "Incremental",
    "units": "request",
    "unitsPlural": "requests",
    "isMetered": true
  }
}

Proactively checking if a customer will have access to X units of a metered feature

const requestedUsage = 10;

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

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

Show Result - has access

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

Show Result - no access

{
  "isFallback": false,
  "hasAccess": false,
  "accessDeniedReason": "RequestedUsageExceedsLimit",
  "isUnlimited": false,
  "usageLimit": 2,
  "currentUsage": 0,
  "requestedUsage": 10,
  "feature": {
    "id": "feature-demo-03",
    "featureType": "Numeric",
    "meterType": "Incremental",
    "units": "request",
    "unitsPlural": "requests",
    "isMetered": true
  }
}

Getting all of the entitlements for a specific customer

const entitlements = await stiggClient.getEntitlements(
  'customer-demo-01',
  'resource-01',       // optional, required for multiple subscription for same product
);

// all the entitlements the customer is entitled to  
entitlements.forEach((entitlement) => {  
  console.log(JSON.stringify(entitlement));  
});

Show Result

[
  {
    "isFallback": false,
    "hasAccess": true,
    "isUnlimited": false,
    "value": 100,
    "feature": {
      "id": "feature-demo-01",
      "featureType": "Numeric",
      "meterType": "None",
      "units": "request",
      "unitsPlural": "requests",
      "isMetered": false
    }
  },
  {
    "isFallback": false,
    "hasAccess": true,
    "feature": {
      "id": "feature-demo-02",
      "featureType": "Boolean",
      "meterType": "None",
      "units": "",
      "unitsPlural": "",
      "isMetered": false
    }
  },
  {
    "isFallback": false,
    "hasAccess": true,
    "isUnlimited": false,
    "usageLimit": 2,
    "currentUsage": 0,
    "requestedUsage": 0,
    "feature": {
      "id": "feature-demo-03",
      "featureType": "Numeric",
      "meterType": "Incremental",
      "units": "request",
      "unitsPlural": "requests",
      "isMetered": true
    }
  }
]

Getting paywall data

Useful for rendering the public pricing page or customer paywall.

const paywallData = await stiggClient.getPaywall();

Show Result

{
  "plans": [
    {
      "id": "plan-stigg-starter",
      "order": 0,
      "displayName": "Starter",
      "description": "For getting started",
      "entitlements": [
        {
          "usageLimit": 100,
          "feature": {
            "id": "feature-demo-01",
            "featureType": "Numeric",
            "description": "",
            "meterType": "None",
            "units": "request",
            "unitsPlural": "requests",
            "displayName": "Feature #1",
            "isMetered": false,
            "metadata": {
              "key": "value"
            }
          },
          "hasUnlimitedUsage": false,
          "displayNameOverride": "Awesome feature #1",
          "hiddenFromWidgets": []
        },
        {
          "usageLimit": 0,
          "feature": {
            "id": "feature-demo-02",
            "featureType": "Boolean",
            "description": "",
            "meterType": "None",
            "displayName": "Feature #2",
            "isMetered": false
          },
          "hasUnlimitedUsage": false,
          "displayNameOverride": null,
          "hiddenFromWidgets": ["PAYWALL"]
        }
      ],
      "inheritedEntitlements": [],
      "pricePoints": [],
      "pricingType": "FREE",
      "defaultTrialConfig": null,
      "compatibleAddons": [],
      "product": {
        "id": "product-stigg",
        "displayName": "Stigg",
        "description": null,
        "metadata": null
      },
      "metadata": null
    }
  ]
}

Subscribing to entitlement and usage updates

The server SDK use a streaming connection to receive updates with low latency, and can notify you when changes to customer entitlements and usage take place. An additional parameter is sent to the subscribed event listeners with data that is relevant for the specific event, for example: for entitlementsUpdated event the extra parameter has information about the customer and the updated entitlements.

// listen to customer entitlement updates
stiggClient.addListener('entitlementsUpdated', (data) => {  
  console.log('entitlements updated: ', data.customerId, data.entitlements);  
});  

// listen to customer usage updates
stiggClient.addListener('usageUpdated', (data) => {  
  console.log('entitlement usage updated', data.entitlement, data.usage);  
});

Example project

Reporting usage measurements to Stigg

The Stigg SDK allows you to report usage measurements for metered features. The reported usage will be used to track, limit and bill the customer’s usage of metered features. Stigg supports metering of usage from the following data sources:

Calculated usage - usage that has been aggregated and calculated by your application. This type is useful for features, such as: seats.
Raw events - raw events from your application, which Stigg filters and aggregates aggregate to calculate customer usage. This type is useful for features, such as: monthly active users (MAUs).

More details about Stigg’s metering and aggregation capabilities can be found here:

Stigg's metering and aggregation capabilities

Reporting of measurements to Stigg should be done only after the relevant resources have been provisioned in your application.
To ensure that the provisioned resources are aligned with the measurements that are reported to Stigg, ensure that customers are not allowed to allocate new resources until an acknowledgement about the processed measurement is received from the Stigg backend.

Validating that a measurement was successfully reported to Stigg is also possible in the customer details section of the relevant customer in the Stigg app.

Calculated usage

// increment usage of a metered feature by 10
await stiggClient.reportUsage({  
  customerId: 'customer-test-id',  
  featureId: 'feature-seats',  
  value: 10,
  resourceId: 'resource-01',      // optional, pass it to report usage for specific resource
});

By default, the value reported should represent the change in usage of the feature, for example user added 2 more seats then the report usage call should have the value of 2. In some cases, it’s more useful to set the usage to some value instead of reporting the change value, it’s possible by passing the updateBehavior parameter:

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

// set usage of a metered feature to 10
await stiggClient.reportUsage({  
  customerId: 'customer-test-id',  
  featureId: 'feature-seats',  
  value: 10,
  updateBehavior: UsageUpdateBehavior.Set,
  resourceId: 'resource-01',      // optional, pass it to report usage for specific resource
});

Show Result

{
  "measurementId": "e7293df0-2d69-4713-9913-10ed06b9b777"
}

Calculated usage measurements can also be reported in bulks

Raw events

// report event of a user login
await stiggClient.reportEvent({
  customerId: 'customer-test-id',
  resourceId: 'resource-01',      // optional, pass it to report event for specific resource
  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, pass it to report event with specific timestamp
});

It’s also possible to send a batch of events in one invocation. To do so, simply pass an array of events to the reportEvent method.

The dimensions field support key value pairs, while keys are strictly of type string values can be string | number | boolean

Granting promotional entitlements

You can grant promotional entitlements for customers using the grantPromotionalEntitlements method.

Revoking promotional entitlements

You can revoke promotional entitlements from customer using the revokePromotionalEntitlements method.

Getting available coupons

const coupons = await stiggClient.getCoupons();

Show Result

[
  {
    "id": "coupon-16e5c7",
    "name": "Test coupon",
    "description": null,
    "metadata": null,
    "discountValue": 5
  }
]

Getting all products

const products = await stiggClient.getProducts();

Show Result

[
  {
    "id": "product-revvenu",
    "displayName": "Revvenu",
    "description": "Example description",
    "metadata": { "recommendedPlan": "plan-revvenu-essentials" },
    "downgradePlan": { "id": "plan-revvenu-basic", "displayName": "Basic" }
  }
]

Estimate subscription cost

You can estimate the subscription cost using the estimateSubscription method. This can help the customer to understand the costs before paying.

// increment usage of a metered feature  
await stiggClient.estimateSubscription({  
	customerId: "customer-demo-01",
  billingPeriod: "MONTHLY",
  planId: "plan-revvenu-growth",
  billableFeatures: [{ 						// optional, required for plans with per unit pricing
    featureId:'feature-01-templates',
    quantity: 2
  }],
  addons: [{  								// optional
  	addonId: 'addon-10-campaigns',  
    quantity: 1  
  }],
  billingInformation: {  					// optional
      taxRateIds: [  
        "txr_1LcTSRE1gVT2zwZV07MIRKdf",  
        "txr_1LcTSRE1gVT2zwZV07MIRKdf"  
      ],  
      taxPerentage: 17,// optional. taxRate will be created if not exists
  },
  promotionCode: "STIGG50",		// optional
  startDate: new Date(), 			// optional
  billingCountryCode: 'US' 		// optional, required for price localization, must be in the ISO-3166-1 format
  resourceId: 'resource-01',  // optional, required for multiple subscription for same product
});

Return fields

{
  total: 'Total after discounts and taxes.',
  totalExcludingTax: 'Total including discounts but excluding tax.',
  subTotal: 'Total before any discount or exclusive tax is applied.',
  tax: 'Tax amount',
  taxDetails: {
    displayName: 'Tax display name.',
    inclusive: 'Specifies if the tax rate is inclusive or exclusive.',
    percentage: 'Tax rate percentage out of 100.',
  },
  discount: {
    type: 'Discount type - `PERCENTAGE` / `FIXED`.',
    value: 'Discount value out of 100.',
    durationType:
      'The duration of the discount - `FOREVER` / `REPEATING` / `ONCE`',
    durationInMonths: 'The duration of the discount in months',
  },
  billingPeriodRange: {
    start: 'Billing period start date',
    end: 'Billing period end date',
  },
  proration: {
    prorationDate: 'The date when the proration occurred',
    credit:
      'The prorated amount of credits to refund the customer in the upcoming invoice',
    debit:
      'The prorated amount of debit to charge the customer in the upcoming invoice',
    netAmount: 'The sum of `debit` and `credit`',
  },
  // Not prorated subscription prices
  subscription: {
    total: 'Total after discounts and taxes.',
    totalExcludingTax: 'Total including discounts but excluding tax.',
    subTotal: 'Total before any discount or exclusive tax is applied.',
    tax: 'Tax amount',
  },
};

Show Result

{
  "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"
  },
  "subscription": {
    "total": {
      "amount": 10,
      "currency": "USD"
    },
    "subTotal": {
      "amount": 20,
      "currency": "USD"
    }
  }
}

You can also estimate the cost of updating an existing subscription using the updateSubscription method, which also returns a breakdown of the proration amounts:

await stiggClient.estimateSubscriptionUpdate({  
  subscriptionId: "subscription-plan-revvenu-growth-da6324",
  billableFeatures: [{ 						// optional, required for subscriptions with per unit pricing
    featureId:'feature-01-templates',
    quantity: 3
  }],
  addons: [{  								// optional
    addonId: 'addon-10-campaigns',  
    quantity: 1  
  }],
  promotionCode: "STIGG50"		// optional
});

Return fields

{
  total: 'Total after discounts and taxes.',
  totalExcludingTax: 'Total including discounts but excluding tax.',
  subTotal: 'Total before any discount or exclusive tax is applied.',
  tax: 'Tax amount',
  taxDetails: {
    displayName: 'Tax display name.',
    inclusive: 'Specifies if the tax rate is inclusive or exclusive.',
    percentage: 'Tax rate percentage out of 100.',
  },
  discount: {
    type: 'Discount type - `PERCENTAGE` / `FIXED`.',
    value: 'Discount value out of 100.',
    durationType:
      'The duration of the discount - `FOREVER` / `REPEATING` / `ONCE`',
    durationInMonths: 'The duration of the discount in months',
  },
  billingPeriodRange: {
    start: 'Billing period start date',
    end: 'Billing period end date',
  },
  proration: {
    prorationDate: 'The date when the proration occurred',
    credit:
      'The prorated amount of credits to refund the customer in the upcoming invoice',
    debit:
      'The prorated amount of debit to charge the customer in the upcoming invoice',
    netAmount: 'The sum of `debit` and `credit`',
  },
  // Not prorated subscription prices
  subscription: {
    total: 'Total after discounts and taxes.',
    totalExcludingTax: 'Total including discounts but excluding tax.',
    subTotal: 'Total before any discount or exclusive tax is applied.',
    tax: 'Tax amount',
  },
};

Show Result

{
  "total": {
    "amount": 2.5,
    "currency": "USD"
  },
  "subTotal": {
    "amount": 5,
    "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": -9.99,
      "currency": "USD"
    },
    "debit": {
      "amount": 14.99,
      "currency": "USD"
    },
    "netAmount": {
      "amount": 5,
      "currency": "USD"
    },
    "prorationDate": "2022-10-26T00:00:00.000Z"
  },
  "subscription": {
    "total": {
      "amount": 2.5,
      "currency": "USD"
    },
    "subTotal": {
      "amount": 5,
      "currency": "USD"
    }
  }
}

Passing of promo codes requires an integration with a billing solution, such as: Stripe.
Promo codes should be generated in the integrated billing solution.
When providing the optional promotionCode parameter, the promo code and associated coupon will validated against the defined restrictions to ensure that they’re applicable for the subscription. If validation fails, a relevant error code would be returned; otherwise, the subscription will include the discounted price.

Migrating subscriptions to the latest plan and add-on version

When changes to plans and add-ons are rolled out only to new subscriptions, grandfathering takes place. In order to prevent a SKU sprawl, Stigg allows you to manually migrate subscriptions to the latest plan and add-on version on a subscription-by-subscription basis.

When the current price of the subscription is different than the latest published package version, during the migration the customer will be charged or credited the prorated amount until the end of the current billing period depending on whether the latest price is more expensive or cheaper than the current subscription price.

To migrate a customer to the latest plan and add-on version:

await stiggClient.MigrateSubscriptionToLatest("subscriptionId", 
                                              SubscriptionMigrationTime.EndOfBillingPeriod);

Archiving customers

When a customer is archived:

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

When Stigg is integrated with a billing solution, customers that are archived in Stigg will still exist in the billing solution to allow upcoming invoices to be finalized. Archiving customers in the billing solution can be done manually in the billing solution.

New customers cannot use the customer ID of archived customers.

To archive a customer:

await stiggClient.archiveCustomer("customer-a18f01");

Persistent cache

To configure a persistent cache store, you can read about it in the persistent cache section.

Offline mode

During local development or testing, you might want to avoid making network requests to the Stigg API. To do this, you can run the Node SDK service in offline mode by enabling the offline option. When enabled, API key validation will always succeed, regardless of the key provided.

const stiggClient = Stigg.initialize({
  apiKey: 'local',
  offline: true
});

In offline mode, the Node SDK respects the global fallback strategyg, and entitlement evaluations are limited to the values defined as fallback entitlements.

const stiggClient = Stigg.initialize({
  apiKey: 'local',
  offline: true,
  entitlementsFallback: {
    'feature-number-of-seats': {
     	hasAccess: true,
    },
    'feature-templates': {
      hasAccess: true,
      usageLimit: 10
    }
  }
});

Only the following methods support offline mode:

getEntitlements
getBooleanEntitlement
getNumericEntitlement
getMeteredEntitlement
reportUsage (noop)
reportEvents (noop)
reloadEntitlements (noop)

All other SDK methods will attempt to send requests to the Stigg API over the network, even when offline mode is enabled

Codebase integration

API and SDK references

Changelog

​Installing the SDK

​Retrieving the server API Key

​Initializing the SDK

​Provisioning customers

​Updating customers

​Getting customer data

​Provisioning subscriptions

​Updating subscriptions

​Canceling subscriptions

​Canceling subscriptions scheduled updates

​Canceling subscriptions pending payment updates

​Listing customers active subscriptions

​Products with a single active subscription

​Products with multiple active subscriptions

​Getting a specific subscription

​Getting the entitlement of a customer to a specific feature

​Generic entitlement check (recommended)

​Checking the entitlement of a boolean feature

​Checking the entitlement of a numeric configuration feature

​Checking if a customer has access to a metered feature

​Proactively checking if a customer will have access to X units of a metered feature

​Getting all of the entitlements for a specific customer

​Getting paywall data

​Subscribing to entitlement and usage updates

Example project

​Reporting usage measurements to Stigg

Stigg's metering and aggregation capabilities

​Calculated usage

​Raw events

​Granting promotional entitlements

​Revoking promotional entitlements

​Getting available coupons

​Getting all products

​Estimate subscription cost

​Migrating subscriptions to the latest plan and add-on version

​Archiving customers

​Persistent cache

​Offline mode

​Full SDK reference

Node.js SDK reference

​SDK changelog

Node.js SDK changelog

Installing the SDK

Retrieving the server API Key

Initializing the SDK

Provisioning customers

Updating customers

Getting customer data

Provisioning subscriptions

Updating subscriptions

Canceling subscriptions

Canceling subscriptions scheduled updates

Canceling subscriptions pending payment updates

Listing customers active subscriptions

Products with a single active subscription

Products with multiple active subscriptions

Getting a specific subscription

Getting the entitlement of a customer to a specific feature

Generic entitlement check (recommended)

Checking the entitlement of a boolean feature

Checking the entitlement of a numeric configuration feature

Checking if a customer has access to a metered feature

Proactively checking if a customer will have access to X units of a metered feature

Getting all of the entitlements for a specific customer

Getting paywall data

Subscribing to entitlement and usage updates

Reporting usage measurements to Stigg

Calculated usage

Raw events

Granting promotional entitlements

Revoking promotional entitlements

Getting available coupons

Getting all products

Estimate subscription cost

Migrating subscriptions to the latest plan and add-on version

Archiving customers

Persistent cache

Offline mode

Full SDK reference

SDK changelog