Installing the SDK
The first step is to install the Stigg SDK as a dependency in your application using your application’s dependency manager: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: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.
waitForInitialization
which return a promise that resolves when the client is ready to use, or rejects when the 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 passsubscriptionParams
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.
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.Getting customer data
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.- 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 theprovisionSubscription()
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
- 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
Subscription cancellation will take place according to the defined product behavior.
Canceling subscriptions scheduled updates
Will cancel all the scheduled updates of the given subscriptionCanceling subscriptions pending payment updates
Will cancel all the pending payment updates of the given subscriptionListing customers active subscriptions
ThegetActiveSubscriptionsList
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: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:Getting a specific subscription
To retrieve extended subscription:Getting the entitlement of a customer to a specific feature
Generic entitlement check (recommended)
ThegetEntitlement
method provides a unified way to check any type of feature entitlement. It automatically returns the appropriate entitlement type based on the feature configuration.
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
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
Useful for rendering the public pricing page or customer paywall.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: forentitlementsUpdated
event the extra parameter has information about the customer and the updated entitlements.
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).
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
updateBehavior
parameter:
Calculated usage measurements can also be reported in bulks
Raw events
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
Getting all products
Estimate subscription cost
You can estimate the subscription cost using theestimateSubscription
method. This can help the customer to understand the costs before paying.
updateSubscription
method, which also returns a breakdown of the proration amounts:
- 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.
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.
New customers cannot use the customer ID of archived customers.
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.Only the following methods support offline mode:
- getEntitlements
- getBooleanEntitlement
- getNumericEntitlement
- getMeteredEntitlement
- reportUsage (noop)
- reportEvents (noop)
- reloadEntitlements (noop)