Node.js SDK

• Fixed: a credit-backed feature whose credit entitlement has a soft limit no longer reports InsufficientCredits when the credit balance reaches zero. Access is now granted, matching the credit entitlement itself.

• Added: optional requestedUsage in getCreditEntitlement options. hasAccess is true only when the remaining balance covers the requested amount. When omitted, the check defaults to 1 credit, as before.

• Removed the info log written each time a read found no entitlement for the requested feature or currency. The returned entitlement is unchanged.

• Internal improvements to how the cache tracks when entitlements and usage were last updated.
• When an API response is missing the usage timestamp for a metered or credit entitlement, the SDK now logs an error and uses the current time.

• Added: eventCount field on each series and point returned by getCreditUsage, with the number of usage events behind the credit consumption.

• Added: optional eventType filter on getCreditLedger. Pass one or more CreditLedgerEventType values (for example CREDITS_GRANTED or CREDITS_CONSUMED) to return only those ledger entries.

• Security: raised the axios dependency to ^1.18.0.

• Added: estimateEventCost and estimateUsageCost methods. They return the credits an event or a usage report would consume, without reporting it.

• Added: consumed field on the credit object returned by reportUsage, with the number of credits the call consumed.

• Added: optional idempotencyKey parameter on reportUsage (single and bulk). Pass a unique key to safely retry a usage report without risking double-counting, matching the existing idempotency pattern on reportEvent and consumeCredits.

• Added: consumeCredits (synchronous) and consumeCreditsAsync (asynchronous) methods to deduct credits directly from a customer’s pool, without reporting usage against a metered feature or requiring an active subscription. Use consumeCredits for strict, real-time enforcement; use consumeCreditsAsync for high-volume, eventually-consistent consumption. See direct credit consumption.
• getCreditEntitlement and getEntitlement continue to return a valid credit balance for customers with no active subscription, so credit governance can run fully decoupled from Stigg subscription management.

• Added: When reportUsage is called for a credit-backed feature, the response now includes a credit object with the updated credit balance — immediately, before the asynchronous metering pipeline settles. credit contains currencyId, currentUsage, usageLimit, and timestamp. Use reportUsage for sub-second, strict credit enforcement; use reportEvent for high-volume, eventually-consistent metering.

• Added: hasSoftLimit field on credit entitlement responses. When a credit entitlement is configured as a soft limit in the plan or add-on, getEntitlement returns hasAccess: true and hasSoftLimit: true even after the credit balance reaches zero. Hard limit (the default) continues to return hasAccess: false when the balance is exhausted. Credit-backed features inherit the wallet’s soft-limit so dependent feature reads stay consistent.

• Added: cancellationDate field when provisioning and updating subscriptions. Pass a future date to schedule cancellation for that exact moment in a single call — no follow-up cancel request needed. On update, omitting the field leaves any existing schedule untouched, passing null clears a previously scheduled cancellation, and passing a date sets or replaces the schedule. Past dates and dates on or before the subscription start date are rejected; trial subscriptions are supported, and setting a date aligns the trial’s trialEndDate to it. See canceling subscriptions.

• Added: groupBy array parameter on getCreditUsage to break down credit consumption by any dimension key attached to reported usage events (e.g., user, model, region). Results are paginated for performance at high event volumes.

• Security: patched vulnerable transitive dependencies.

• Added: support for disabling Redis cache expiration by setting redis.ttl to a negative value (e.g. -1, matching Redis’s own no-expiry convention). Entitlement entries are then written to Redis without the EX flag and remain authoritative through extended Stigg Cloud outages. Default behavior is unchanged (TTL stays on when redis.ttl is unset). Invalidation continues to flow through the persistent-cache-service pipeline. To get end-to-end no-expiry behavior the same negative value must also be set on persistent-cache-service (KEYS_TTL_IN_SECS=-1, v3.6.1+) — see persistent caching.

• Added: startDate and endDate parameters on getCreditUsage. Pass specific start and end timestamps to retrieve credit consumption data for an exact time window, in addition to the existing preset period enums (last week, month, year, etc.). See customer credits.

• Changed: entitlement reads now check the customer’s entitlements before the customer-level access-denied reason. Credit entitlements from standalone grants are evaluated normally even when the customer has no active subscription. Feature entitlements without a subscription still return NoActiveSubscription.

• Added: invoiceDaysUntilDue on SubscriptionBillingInfo, to set the invoice due days when provisioning a subscription.

• Added: Support for plan-level and add-on-level credit entitlements — recurring credit grants that are automatically issued and reset each billing period when a customer subscribes.
• Added: Credit entitlements are reflected in getCreditEntitlement() alongside all other active grants (top-ups, promotional credits).
• Added: entitlements in subscription provisioning now accepts credit entitlement configurations for custom plans.
• Recurring grants work seamlessly with existing one-time top-ups and prepaid credit purchases.

• Added: billingCycleAnchor property when provisioning and updating subscriptions. Accepts SubscriptionBillingCycleAnchor.UNCHANGED (default) to keep the existing billing cycle anchor, or SubscriptionBillingCycleAnchor.NOW to reset it to the current timestamp.

• ⚠️ Deprecated: getCreditBalance() (please use getCreditEntitlement() instead). getCreditEntitlement() reads directly from the SDK’s local cache, significantly reducing latency and removing rate-limit concerns. It returns the same data: currentBalance, totalConsumed, totalGranted, and currency.

• Added: getCreditEntitlement() method for low-latency retrieval of customer credit balance from the local cache.
• Added: Support for provisioning subscriptions with variable recurring credit grant entitlements.

• Added: includeInactiveSubscriptions parameter on getUsageHistoryV2. When set to true, usage history is returned regardless of whether the customer currently has an active subscription. If they do have an active subscription, the response also includes a markers array containing the subscription’s usage reset timestamps.

• Added: entitlements on provisionSubscription, updateSubscription, createSubscription and applySubscription, accepting both feature and credit entitlements (SubscriptionEntitlementV2).
• ⚠️ Deprecated: subscriptionEntitlements (use entitlements instead).

• The cache layer was extracted into the new @stigg/cache-core and @stigg/cache-redis-store packages, which the SDK now depends on. No API or behavior change.

• The SDK is now published from the stiggio/stigg-sdk monorepo to the public npm registry. No API change.

• Enhanced getCreditEntitlement to return currency information.

• Added: packageEntitlements and inheritedPackageEntitlements on paywall plans and add-ons, returning both feature and credit entitlements.
• ⚠️ Deprecated: entitlements and inheritedEntitlements on paywall plans and add-ons (use packageEntitlements and inheritedPackageEntitlements instead).

• Added: getEntitlementV2 method, returning a feature or credit entitlement for a customer.
• Improved: getEntitlementsStateV2 returns both feature and credit entitlements.

• Added: usagePeriodEnd on credit entitlements, read from the cache.

• Added: optional integrationId parameter on importCustomerBulk and importSubscriptionBulk, to target a specific billing integration.

• Added compatibility with persistent-cache-service v3.0.0 and its new Redis data structure for credit entitlements.
• Note: This version must be deployed before upgrading persistent-cache-service to v3.0.0. See the persistent-cache-service v3.0.0 changelog for migration steps.

• Added: charges on provisionSubscription, applySubscription, updateSubscription, previewSubscription, estimateSubscription and estimateSubscriptionUpdate.

• Added: AccessDeniedReason.CustomerIsArchived, returned when the customer is archived. The customer is cached so repeated checks don’t refetch.

• Added: Support for configuring and managing credit auto-recharge settings, including trigger balance, target top-up amount, and monthly spend limit.

• ⚠️ Changed: getCreditLedger is now paginated and returns { data, pageInfo, totalCount } instead of an array of ledger events.

• Fixed: credit queries are no longer served from the GraphQL client cache, so balances and grants are always current.

• Added: getEntitlementsState method, returning a customer’s entitlements together with the customer-level access-denied reason.
• ⚠️ Deprecated: getEntitlements (use getEntitlementsState instead).

• Added: awsMarketplacePlanDimension on plans and awsMarketplaceProductId on products.

• Breaking change: Entitlements retrieval logic now correctly identifies the underlying cause for missing entitlements, whether due to no active subscription, a missing customer, or no assigned entitlements.
• Note: If using a Persistent Caching Service, it must be updated before upgrading the Sidecar to ensure data integrity.

​

Migration steps

1. Upgrade the Persistent Caching Service image to version 2.40.1 or later.
2. Upgrade the Node SDK to version 4.0.0 or later.

• Added getCreditLedger and getCreditUsage methods.

• Added void credit grant voidCreditGrant.

• Added credit balance subscription handling with automatic entitlement updates, expiration checks, and cache mapping for credit rate and validity.

• Added credit rate mapping.

• Added awsMarketplaceCustomerId to update and provision customers.

• Updated SDK to prevent dependency on compromised NPM packages

• Added: grantPromotionalEntitlementsGroup or granting a promotional entitlements group - all entitlements that are not already granted to a customer, need to be included in the request.
• Added: revokePromotionalEntitlementsGroup for revoking all of the entitlements of a group, unless they are a part of a different group.
• Added: unlinkPromotionalEntitlementsGroup for removing the references of the group from promotional entitlements that are a part of it, while keep granting access to those entitlements.

• Added: CancelSubscription.awaitSubscriptionCancellation for controlling whether to wait for confirmation from billing solutions that are integrated with Stigg before marking subscription as canceled in Stigg

• Added: grantCredits, getCreditGrants and getCreditBalance methods.

• Added: AccessDeniedReason.Revoked for determining when an entitlement has been explicitly revoked.

• Added: getEntitlement method - a unified way to check any type of feature entitlement (boolean, numeric, or metered) that automatically returns the appropriate entitlement type based on the feature configuration

• Added: SubscriptionBillingInfo.prorationBehavior for controlling the proration behavior when provisioning and updating subscriptions. The new parameter accepts the following value
• CREATE_PRORATIONS - bill for proration immediately. This is the default behavior.
• INVOICE_IMMEDIATELY - include prorated charges in the upcoming invoice.
• NONE - don’t prorate subscription changes.

• Added: prorationBehavior on SubscriptionBillingInfo.

• Improved: when Redis is a read-only replica, the SDK no longer fails while trying to take a distributed lock. Entitlements are fetched from the API instead.

• Improved: SDK initialization handles an unavailable Redis. Initialization waits for the entitlements service to be ready and, when remote config is enabled, validates the API key in parallel.

• Changed: the API request timeout for fetching entitlements is shorter, so a slow API falls back to cached or fallback entitlements sooner. Timeouts now raise OperationTimeoutError, naming the operation.

• Added: AccessDeniedReason.FeatureTypeMismatch, returned when a typed read (for example getBooleanEntitlement) targets a feature of a different type.

• Removed: entitlement check reporting from the SDK. Entitlement checks no longer send tracking requests to Stigg.

• Added: getEnumEntitlement method for enum features, with optional requestedValues.

• Added: getSubscriptions endpoint that allows retrieving all of customers’ subscriptions

• Added: Redis client errors are emitted as events.
• Improved: errors during SDK initialization go through the standard error handling and are logged with their details.

• Added: previewNextInvoice method, to preview a subscription’s next invoice.

• Added: apiKeyInvalid and networkRequestFailed events. networkRequestFailed carries the error message, error code, trace ID, request and response.

• Added: cacheHit and cacheMiss events for monitoring the in-memory entitlements cache.

• Added: optional integrationId on SubscriptionBillingInfo, BillingInfo and updateCustomer, to target a specific billing integration.

• Security: upgraded axios to patch CVE-2025-27152.

• Added: SubscriptionInvoiceFragment.attemptCount

• Added: Ability to pass taxId on updateCustomer.billingInfo.taxIds

• Security: upgraded the nanoid dependency.

• Security: upgraded axios to patch an SSRF vulnerability.

• Added: salesforceId to provisionCustomer, updateCustomer , provisionSubscription, importCustomerBulk and importSubscriptionBulk

• Added: timeout client configuration for API requests, in milliseconds. Defaults to 60000.

• Added: offline mode

• Added: SubscriptionCouponDiscountInput.amounts_off
• Added: SubscriptionCouponDiscountInput.description
• Added: SubscriptionCouponDiscountInput.duration_in_months
• Added: SubscriptionCouponDiscountInput.name
• Added: SubscriptionCouponDiscountInput.percent_off

• Added: getUsageHistoryV2
• ⚠️ Deprecated: fetchUsageHistory(please use getUsageHistoryV2 instead)
• Changed:
  • Input Object
    • New field - groupBy list of dimensions to group usage history by.
  • Output Object
    • result[i].date renamed to series[0].point[i].timestamp
    • result[i].value renamed to series[0].point[i].value
    • result[i].isResetPoint renamed to series[0].point[i].isResetPoint
      • Old Value: true if and only if usage was reset due to periodic reset.
      • New Value: true if and only if usage was reset due to periodic reset or due to a plan transition.
    • New field markers - array of markers for usage reset reason (periodic change / plan transition)

• Added: ability to override prices when there’s a scheduled update in place

• Added: provisionSubscription.priceOverrides
• Added: applySubscription.priceOverrides

• Added: support for price localization in fixed fee coupons

• Added: delegateSubscriptionToCustomer()
• Added: transferSubscriptionToResource()
• 🟡 Deprecated: transferSubscription() method (please use transferSubscriptionToResource() instead)

• Fixed: when access to entitlement was denied due to the reaching of a budget cap, getMeteredEntitlements returned AccessDeniedReason.UNSPECIFIED instead of AccessDeniedReason.BudgetExceeded.

• Added: ability to estimate the subscription cost when the payment of the subscription is delegated to a different customer using:
  • previewSubscription.payingCustomerId,
  • estimateSubscription.payingCustomerId
  • estimateSubscriptionUpdate.payingCustomerId

• Added: ability to more easily determine the usage period of metered entitlements using:
  • Entitlement.usagePeriodStart
  • Entitlement.usagePeriodEnd
• 🟡 Deprecated: Entitlement.nextResetDate field

• Added: ability to delegate payment of a provisioned subscription to a different customer using:
  • provisionSubscription.payingCustomerId
  • applySubscription.payingCustomerId
  • SlimSubscriptionFragmentV2Fragment.payingCustomer
  • FullSubscription.payingCustomer

• Added: ability to apply a coupon to a subscription using the Stigg coupon ID using:
  • provisionSubscription.appliedCoupon
  • applySubscription.appliedCoupon
  • updateSubscription.appliedCoupon
  • previewSubscription.appliedCoupon
  • estimateSubscription.appliedCoupon
  • estimateSubscriptionUpdate.appliedCoupon

• Added: budget.limit on a plan’s defaultTrialConfig.

• Added: enableRemoteConfig client configuration. Set it to false to skip loading the SDK configuration from Stigg on initialization. Defaults to true.

• Fixed: Stigg is now available as a named export as well as the default export.

• Changed: provisionCustomer no longer generates a customer ID when none is passed. The ID returned by Stigg is used instead.

• Removed: the @sentry/node dependency. The SDK no longer reports errors to Sentry.

• Added: budget cap support. Metered entitlement checks return hasAccess: false with AccessDeniedReason.BudgetExceeded when the customer’s budget is exhausted.

• Changed: UpdateSubscription.subscriptionEntitlements does not require the full list of entitlements when only needing to add or update specific entitlements

• Fixed: Edge API requests are retried on timeout. The Edge request timeout is now 15 seconds.

• Improved: Redis reads and writes for entitlements and usage, reducing round trips.

• Bug fixes

• Bug fixes

• Added: a default Redis commandTimeout of 60 seconds.

• Added: ability to get the list of active subscriptions from Edge using getActiveSubscriptionsList()

• Added: ability to get the details of a specific subscription using getSubscription()

• Added: paymentCollectionMethod on provisionSubscription and applySubscription, and on FullSubscription.
• The SDK is now published with public access on npm.

• Added: support for the new subscription bulk import input fields. ImportSubscription now accepts all fields of ImportSubscriptionInput.

• Fixed: a race condition when notifying other SDK instances after a distributed entitlements fetch.

• Improved: logs when no entitlement is found now include the customer, resource, feature and access-denied reason.

• Added: with a Redis cache, only one SDK instance fetches a customer’s entitlements from the API after a cache miss. Other instances wait for it to finish and read the result from Redis, reducing load on the API. Enabled by default; set redis.disableDistributedEntitlementsFetching to true to turn it off.
• Fixed: getEntitlements with Redis now handles a missing feature usage record.

• Fixed: entitlements are no longer refetched from the API when the customer exists in the cache but has no entitlement for the requested feature.

• Improved: concurrent entitlement refetches for the same customer reuse the ongoing request.

• Added: ability to ignore customer and subscriptions that have been updated since the last import by passing ImportCustomer.updatedAt and ImportSubscriptionInput.updatedAt

• Improved: WebSocket throttle errors are logged as info rather than errors.

• Added: blockSize on Price.

• Added: compatiblePackageGroups on paywall plans, with minItems and freeItems options.
• Added: maxQuantity and dependencies on add-ons.

• Removed: the redis.backwardCompatibleLock option added in 3.12.0.

• ⚠️ Changed: the dontProrate flag on cancelSubscription was renamed to prorate.

• Added: dontProrate flag on cancelSubscription.

• Fixed: getMeteredEntitlement refetches entitlements from the API when the feature usage is missing from Redis.

• Added: redis.backwardCompatibleLock option, for running alongside an older persistent cache service.
• Improved: errors updating feature usage after a network fetch are logged through the SDK logger.

• Added: ability to provision backdated subscriptions usingSubscriptionBillingInfo.isBackdated

• Added: ability to determine the billing period of a specific price usingPrice.billingCadence

• Added: ability to determine customer’s AWS Marketplace ID using SlimCustomer.awsMarketplaceCustomerId

• Added: Edge API requests use a timeout, keep-alive connections and up to 3 retries.

• Added: soft limit support. hasSoftLimit is returned on entitlements, package entitlements, promotional entitlements and subscription entitlements, and a metered entitlement with a soft limit grants access after its usage limit is reached.

• Added: optional clientName and clientVersion client configuration, sent with API requests.

• Added: ability to remove a payment method from a customer using detachCustomerPaymentMehod()

• Added: ability to get plans that are not visible to customers usingGetPaywall.includeHiddenPlans