JavaScript SDK

• ⚠️ Breaking: a metered check without requestedUsage now asks for one unit of the limit, so a customer who has reached the limit is denied. Previously it was granted. Credit checks already asked for 1 credit by default and are unchanged.
  • Note: passing requestedUsage: 0 returns the previous answer.
• ⚠️ Breaking: requestedUsage on a metered feature with a unit transformation is now converted into the limit’s units before it’s compared. Previously it was compared as sent.
• Changed: usage is compared with the limit at 5-decimal precision, for metered and credit entitlements alike, so 0.1 + 0.2 against a limit of 0.3 is granted.

• Added: brand and walletType on the customer’s paymentMethodDetails. brand is the card brand reported by the billing provider, for example visa, mastercard or amex. walletType is the digital wallet the card was added through, for example apple_pay or google_pay. Both are null when the billing provider doesn’t report them, so a null walletType doesn’t prove the card is a regular one: cards saved before this field existed have no value.

• No functional change to the JavaScript SDK. This release only bumped the package version to track releases of other packages in the monorepo.

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

• Internal improvements to how cached entitlements and usage track when they were last updated. No API change.

​

Credit isFallback: telling “no data” from “not entitled”

const noEntitlementReasons = [
  AccessDeniedReason.EntitlementNotFound,
  AccessDeniedReason.CustomerNotFound,
  AccessDeniedReason.CustomerResourceNotFound,
  AccessDeniedReason.NoActiveSubscription,
  AccessDeniedReason.CustomerIsArchived,
];
const hasBalanceData =
  !entitlement.isFallback &&
  (entitlement.accessDeniedReason == null ||
    !noEntitlementReasons.includes(entitlement.accessDeniedReason));

• Added: AirwallexCheckoutCredentials to the checkout state’s billingCredentials union, and RECEIVED to the billing vendor identifiers.

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

• Fixed: getCreditEntitlement now defaults to the resourceId set in the client configuration when none is passed, matching getCreditUsage, getCreditBalance and getCreditGrants. Previously it read customer-level credit entitlements and returned the fallback for resource-scoped credit subscriptions. An explicit resourceId still takes precedence.

• Added: hasSoftLimit field on CreditEntitlement. When a credit entitlement is configured as a soft limit, 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: pageInfo on the getCreditUsage result, for cursor pagination.

• Security: patched vulnerable transitive dependencies.

• 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: 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.
• Added: Support for provisioning subscriptions with variable recurring credit grant entitlements.

• Fixed: importing the SDK during Node.js server-side rendering no longer crashes on a bare window.FormData reference.

• Fixed: the ESM bundle no longer drops some exports.

• 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: entitlementsV2 on CustomerPortal, returning both feature and credit entitlements.
• ⚠️ Deprecated: CustomerPortal.entitlements (use entitlementsV2 instead).

• Added: credit entitlements on paywall plans and add-ons. PackageEntitlement is now a union of feature and credit entitlements, and add-ons expose packageEntitlements.
• ⚠️ Deprecated: the legacy entitlements fields on paywall plans and add-ons.

• Added: usagePeriodEnd on CreditEntitlement.

• Added: taxIds on subscription billing information, and the full billing information is now passed through on preview and estimate calls, to support checkout with a tax ID.

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

• Added support for subscriptions filter by resourceId and plan (planId/displayName).

• Changed: entitlements are loaded with the entitlements-state query, which also returns the customer-level access-denied reason.

• Added: maxQuantity on Addon.

• Added: showWidgetWatermark on paywall and checkout data, read from the SDK configuration.

• Added: creditRate on paywall prices.

• Added: getCreditUsage method.

• Added: getCreditLedger method.

• Added: an ESM build of the SDK.

• Updated SDK to prevent dependency on compromised NPM packages

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

• Added: createPaymentSession method.

• Changed: getCreditBalance now takes the customer and resource from the client configuration, so its input is optional.

• Added: getCreditBalance and getCreditGrants methods.

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

• ⚠️ Changed: the prorationBehavior type on SubscriptionBillingInfo is now SubscriptionProrationBehavior.

• Added: prorationBehavior on SubscriptionBillingInfo.

• Added: enumValues on package entitlements.

• 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: hiddenFromWidgets on add-on entitlements.

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

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

• Added: optional integrationId on subscription billing information, to target a specific billing integration.

• Added: ability to determine the number of attempts that were made to collect payment for a generated invoice when Stigg is integrated with Stripe using the latestInvoice.attemptCount property of the getActiveSubscriptions() and getSubscription() endpoints

• Added: support for offline mode

• Added: GetUsageHistoryV2
• ⚠️ Deprecated: GetUsageHistory(please use GetUsageHistoryV2 instead)
• Changed:
  • Input Object:
    • customerRefId renamed to customerId
    • resourceRefId renamed to resourceId
    • featureRefId renamed to featureId
    • resetPeriod removed
    • yearlyResetPeriodConfiguration removed
    • monthlyResetPeriodConfiguration removed
    • weeklyResetPeriodConfiguration removed
  • Output Object
    • startDate removed
    • endDate removed
    • usageMeasurements[i].date renamed to series[0].point[i].timestamp
    • usageMeasurements[i].value renamed to series[0].point[i].value
    • usageMeasurements[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.
    • groups[i].groupInfo[j].key renamed to series[i].tags[j].key
    • groups[i].groupInfo[j].value renamed to series[i].tags[j].value
    • groups[i].usageMeasurements[j].date renamed to series[i].point[j].timestamp
    • groups[i].usageMeasurements[j].value renamed to series[i].point[j].value
    • groups[i].usageMeasurements[j].isResetPoint renamed to series[i].point[j].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.

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

• Added: support for price localization in fixed fee coupons

• 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:
  • MeteredEntitlement.usagePeriodStart
  • MeteredEntitlement.usagePeriodEnd
• 🛑 Removed: MeteredEntitlement.nextResetDate

• Fixed: the entitlements cache TTL is now measured from the last fetch rather than from the date entitlements last changed. Entitlements that haven’t changed recently are no longer refetched on every read.

• Improved: reading an entitlement for a feature the customer isn’t entitled to no longer triggers a refetch.

• Added: payingCustomerId on subscription previews and estimates, and payingCustomer on subscriptions, for subscriptions paid by a different customer.

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

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

• 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()