Initializing client instance with client api key. You can either pass the customer id when initializing the client instance or using setCustomerId function as shown below.
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}
For Multi-instance products, set the customer resource ID of the user that’s accessing your app, usually after the customer enters into a resource context:
Getting all of the entitlements of a specific customer
const entitlements = await stiggClient.getEntitlements();// all the entitlements the customer is entitled to entitlements.forEach((entitlement) => { console.log(JSON.stringify(entitlement)); });
const entitlement = stiggClient.getBooleanEntitlement({ featureId: 'feature-demo-02'});if (entitlement.hasAccess) { // customer has access to the feature } else { // no access, offer an upsell }
Checking the entitlement for a numeric configuration feature
const entitlement = stiggClient.getNumericEntitlement({ featureId: 'feature-demo-01'});if (entitlement.hasAccess) { // get the entitlement numeric value that is defined for the feature console.log(entitlement.value); }
Checking if a customer has access to a metered feature
const entitlement = stiggClient.getMeteredEntitlement({ featureId: 'feature-demo-03'});if (entitlement.hasAccess) { // has access and the requested usage is within the allowed quota } else { // the customer has exceeded his quota for this feature }
Proactively checking if a customer will have access to X units of a metered feature
const requestedUsage = 10;const entitlement = stiggClient.getMeteredEntitlement({ featureId: 'feature-demo-03', options: { requestedUsage } });if (entitlement.hasAccess) { // has access and the requested usage is within the allowed quota } else { // the customer has exceeded his quota for this feature }
The getActiveSubscriptionsList method returns a list of slim subscription data, for extended data for a specific subscription use getSubscription method.
const subscriptions = await stiggClient.getActiveSubscriptionsList({ resourceId: 'resource-01', // optional, pass it to get subscription of specific resource});
In addition, there’s an option to pass a list of resource Ids
const subscriptions = await stiggClient.getActiveSubscriptionsList({ resourceIds: ['resource-01', 'resource-02', 'resource-03' ], // optional, pass it to get list of resources});
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", planId: "plan-revvenu-growth", billableFeatures: [{ // optional, required for plans with per-unit pricing featureId:'feature-01-templates', quantity: 2 }], billingPeriod: "MONTHLY", addons: [{ // optional addonId: 'addon-10-campaigns', quantity: 1 }], promotionCode: "STIGG50", // optional startDate: new Date(), // optional billingCountryCode: 'US', // optional, required for price localization, must be in the ISO-3166-1 format billingInformation: { taxPercentage: 17 // optional. taxRate will be created if not exists }});
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', },};
You can also estimate the cost of updating an existing subscription using the updateSubscription method, which also returns a breakdown of the proration amounts:
{ 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', },};
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 initiating checkout using Stigg, the user is expected to be redirected and land on the successUrl destination page in the case of a successful payment.
Due to the async nature of webhooks from Stripe, the subscription might not be yet provisioned in your Stigg account. To make sure that the new subscription has been activated in this scenario, you can utilize the waitForCheckoutCompleted method to have an indication if the checkout is still in progress or not. Once the promise resolves, the subscription has been successfully activated and new entitlements were granted. If there’s a timeout or a network error during that time, the promise is rejected with the error.
For example, you can present a loading animation until the promise returned from the method is resolved.
// in the context of the `successUrl` page, // wait for the subscription to become active and entitlements to be updatedasync function onPageLoad(){ showLoadingIndicator(); try { await stiggClient.waitForCheckoutCompleted(); } catch (err) { // an error occurred while waiting for checkout to complete, // can be a network error or a timeout. // inform the customer to try again or contact support. showErrorMessage(); } finally { hideLoadingIndicator(); }}window.addEventListener('load', (event) => { onPageLoad(); });
For Multi-instance products, clear the customer ID of the user that’s accessing your app, usually after the customer exit the context of specific resource:
Stigg’s SDK refreshes its cache of customer entitlements and usage data upon initialization (for example: when a page is refreshed), as well as periodically every 30 seconds.
After performing an operation on the backend that can modify the customer entitlements or the usage of a feature (for example: updating subscriptions or reporting usage), it’s useful to immediately refresh the cache.
During local development or testing, you might want to avoid making network requests to the Stigg API. To do this, you can run the JS SDK in offline mode by enabling the offline option. When enabled, API key validation will always succeed, regardless of the key provided.
In offline mode, the JS SDK respects the global fallback strategy, and entitlement evaluations are limited to the values defined as fallback entitlements.
