> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stigg.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Node.js SDK

<Update label="4.45.0" description="2026-06-23">
  **Synchronous credit balance updates via `reportUsage`**

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

  **Credit wallet soft limit**

  * 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.
</Update>

<Update label="4.44.0" description="2026-06-14">
  **Schedule subscription cancellation on a specific date**

  * 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](/documentation/managing-customers-and-subscriptions/subscriptions/canceling-subscriptions).
</Update>

<Update label="4.43.0" description="2026-06-01">
  **Credit usage breakdown by event dimensions**

  * 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.
</Update>

<Update label="4.41.0" description="2026-05-18">
  * 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](/documentation/high-availability-and-scale/persistent-caching).
</Update>

<Update label="4.40.0" description="2026-05-10">
  **Credit usage date filters**

  * 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](/documentation/modeling-your-pricing-in-stigg/credits/customer-credits).
</Update>

<Update label="4.34.0" description="2026-03-31">
  **Recurring credit grants in plans and add-ons**

  Vendors can now configure recurring credit grants as entitlements that can be directly attached to any plan or add-on in Stigg. Currently, monthly and yearly recurring grants without rollover are supported.

  * 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.
</Update>

<Update label="4.33.1" description="2026-03-19">
  * 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.
</Update>

<Update label="4.32.0" description="2026-03-17">
  * ⚠️ 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`.
</Update>

<Update label="4.30.1" description="2026-03-17">
  * 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.
</Update>

<Update label="4.29.3" description="2026-04-29">
  * 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.
</Update>

<Update label="4.19.0" description="2026-02-26">
  * Enhanced `getCreditEntitlement` to return currency information.
</Update>

<Update label="4.12.1" description="2026-02-04">
  * 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](/api-and-sdks/changelog/backend-graphql/persistent-cache) for migration steps.
</Update>

<Update label="4.6.0" description="2026-01-24">
  * Added: Support for configuring and managing credit auto-recharge settings, including trigger balance, target top-up amount, and monthly spend limit.
</Update>

<Update label="4.0.0" description="2025-10-29">
  * **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.
</Update>

<Update label="3.96.0" description="2025-09-29">
  * Added `getCreditLedger` and `getCreditUsage` methods.
</Update>

<Update label="3.95.0" description="2025-09-29">
  * Added void credit grant `voidCreditGrant`.
</Update>

<Update label="3.94.0" description="2025-09-29">
  * Added credit balance subscription handling with automatic entitlement updates, expiration checks, and cache mapping for credit rate and validity.
</Update>

<Update label="3.93.0" description="2025-09-25">
  * Added credit rate mapping.
</Update>

<Update label="3.92.0" description="2025-09-23">
  * Added `awsMarketplaceCustomerId` to update and provision customers.
</Update>

<Update label="3.89.1" description="2025-09-09">
  * Updated SDK to prevent dependency on [compromised NPM packages](https://www.aikido.dev/blog/npm-debug-and-chalk-packages-compromised)
</Update>

<Update label="3.89.0" description="2025-09-04">
  * 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.
</Update>

<Update label="3.86.0" description="2025-09-02">
  * 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
</Update>

<Update label="3.84.0" description="2025-09-01">
  * Added: `AccessDeniedReason.Revoked` for determining when an entitlement has been explicitly revoked.
</Update>

<Update label="3.82.0" description="2025-08-21">
  * 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
</Update>

<Update label="3.80.0" description="2025-08-15">
  * 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.
</Update>

<Update label="3.70.1" description="2025-06-26">
  * Added: `getSubscriptions` endpoint that allows retrieving all of customers' subscriptions
</Update>

<Update label="3.62.0" description="2025-02-23">
  * Added: `SubscriptionInvoiceFragment.attemptCount`
</Update>

<Update label="3.61.0" description="2025-01-30">
  * Added: Ability to pass taxId on `updateCustomer.billingInfo.taxIds`
</Update>

<Update label="3.58.0" description="2025-01-19">
  * Added: `salesforceId` to `provisionCustomer`, `updateCustomer` , `provisionSubscription`, `importCustomerBulk` and `importSubscriptionBulk`
</Update>

<Update label="3.56.1" description="2024-12-25">
  * Added: [offline mode](/api-and-sdks/integration/backend/nodejs#offline-mode)
</Update>

<Update label="3.56.0" description="2024-12-17">
  Coupon discount changes:

  * Added: `SubscriptionCouponDiscountInput.amounts_off`
  * Added: `SubscriptionCouponDiscountInput.description`
  * Added: `SubscriptionCouponDiscountInput.duration_in_months`
  * Added: `SubscriptionCouponDiscountInput.name`
  * Added: `SubscriptionCouponDiscountInput.percent_off`

  Usage history changes:

  * 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)
</Update>

<Update label="3.55.0" description="2024-12-08">
  * Added: ability to override prices when there's a scheduled update in place
</Update>

<Update label="3.54.0" description="2024-12-02">
  * Added: `provisionSubscription.priceOverrides`
  * Added: `applySubscription.priceOverrides`
</Update>

<Update label="3.51.0" description="2024-11-21">
  * Added: support for price localization in fixed fee coupons
</Update>

<Update label="3.50.2" description="2024-11-20">
  * Added: `delegateSubscriptionToCustomer()`
  * Added: `transferSubscriptionToResource()`
  * 🟡 Deprecated: `transferSubscription()` method (please use `transferSubscriptionToResource()` instead)
</Update>

<Update label="3.50.1" description="2024-10-16">
  * Fixed: when access to entitlement was denied due to the reaching of a budget cap, `getMeteredEntitlements`  returned `AccessDeniedReason.UNSPECIFIED` instead of `AccessDeniedReason.BudgetExceeded`.
</Update>

<Update label="3.50.0" description="2024-10-14">
  * 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`
</Update>

<Update label="3.48.0" description="2024-10-08">
  * Added: ability to more easily determine the usage period of metered entitlements using:
    * `Entitlement.usagePeriodStart`
    * `Entitlement.usagePeriodEnd`
  * 🟡 Deprecated: `Entitlement.nextResetDate` field
</Update>

<Update label="3.45.0" description="2024-09-02">
  * Added: ability to delegate payment of a provisioned subscription to a different customer using:
    * `provisionSubscription.payingCustomerId`
    * `applySubscription.payingCustomerId`
    * `SlimSubscriptionFragmentV2Fragment.payingCustomer`
    * `FullSubscription.payingCustomer`
</Update>

<Update label="3.44.0" description="2024-08-27">
  * 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`
</Update>

<Update label="3.38.0" description="2024-07-01">
  * Changed: `UpdateSubscription.subscriptionEntitlements` does not require the full list of entitlements when only needing to add or update specific entitlements
</Update>

<Update label="3.36.0" description="2024-06-24">
  * Bug fixes
</Update>

<Update label="3.35.0" description="2024-06-20">
  * Bug fixes
</Update>

<Update label="3.33.0" description="2024-06-20">
  * Added: ability to get the list of active subscriptions from Edge using `getActiveSubscriptionsList()`
</Update>

<Update label="3.32.0" description="2024-06-18">
  * Added: ability to get the details of a specific subscription using `getSubscription()`
</Update>

<Update label="3.23.0" description="2024-05-02">
  * Added: ability to ignore customer and subscriptions that have been updated since the last import by passing `ImportCustomer.updatedAt` and `ImportSubscriptionInput.updatedAt`
</Update>

<Update label="3.11.0" description="2024-03-17">
  * Added: ability to provision backdated subscriptions using`SubscriptionBillingInfo.isBackdated`
</Update>

<Update label="3.9.0" description="2024-03-07">
  * Added: ability to determine the billing period of a specific price using`Price.billingCadence`
</Update>

<Update label="3.7.1" description="2024-03-01">
  * Added: ability to determine customer's AWS Marketplace ID using `SlimCustomer.awsMarketplaceCustomerId`
</Update>

<Update label="3.3.0" description="2024-01-30">
  * Added: ability to remove a payment method from a customer using `detachCustomerPaymentMehod()`
</Update>

<Update label="3.1.0" description="2024-01-25">
  * Added: ability to get plans that are not visible to customers using`GetPaywall.includeHiddenPlans`
</Update>