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

# Ruby SDK

<Update label="6.14.0" description="2026-07-08">
  **Direct credit consumption**

  * Added: `consume_credits` (synchronous) and `consume_credits_async` (asynchronous) methods to deduct credits directly from a customer's pool, without reporting usage against a metered feature or requiring an active subscription. Use `consume_credits` for strict, real-time enforcement; use `consume_credits_async` for high-volume, eventually-consistent consumption. See [direct credit consumption](/documentation/modeling-your-pricing-in-stigg/credits/credits-core-concepts#direct-credit-consumption).
  * `get_credit_entitlement` and `get_entitlement` continue to return a valid credit balance for customers with no active subscription, so credit governance can run fully decoupled from Stigg subscription management.
</Update>

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

  * Added: When `report_usage` 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 `currency_id`, `current_usage`, `usage_limit`, and `timestamp`. Use `report_usage` for sub-second, strict credit enforcement; use `report_event` for high-volume, eventually-consistent metering.

  **Credit wallet soft limit**

  * Added: `has_soft_limit` field on credit entitlement responses. When a credit entitlement is configured as a soft limit, `get_entitlement` returns `is_granted: true` and `has_soft_limit: true` even after the credit balance reaches zero. Credit-backed features inherit the wallet's soft-limit so dependent feature reads stay consistent.
</Update>

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

  * Added: `group_by` array parameter on `get_credit_usage` 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="6.8.0" description="2026-05-10">
  **Credit usage date filters**

  * Added: `start_date` and `end_date` parameters on `get_credit_usage`. Pass specific start and end timestamps to retrieve credit consumption data for an exact time window, in addition to the existing preset period enums. See [customer credits](/documentation/modeling-your-pricing-in-stigg/credits/customer-credits).
</Update>

<Update label="6.6.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="6.2.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="6.40.0" 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="5.74.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="5.0.0" description="2025-11">
  This major version reflects a monorepo-wide version increment driven by a breaking change in the **Python SDK** (pydantic v1 → v2 dependency update). There are **no breaking changes** for the Ruby SDK in this version.
</Update>

<Update label="4.5.0" description="2025-11-02">
  This major version reflects a monorepo-wide version increment driven by breaking changes in the **Node.js and Sidecar SDKs** (entitlements retrieval logic). There are **no breaking changes** for the Ruby SDK in this version.
</Update>

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

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

<Update label="3.73.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.72.0" description="2025-09-25">
  * Added credit rate mapping.
</Update>

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

<Update label="3.68.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.64.0" description="2025-09-03">
  * Added support for subscriptions filter by resourceId and plan (planId/displayName).
</Update>

<Update label="3.59.2" 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.40.0" description="2025-09-01">
  * Added: `AccessDeniedReason.Revoked` for determining when an entitlement has been explicitly revoked.
</Update>

<Update label="3.22.2" 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="2.448.1" description="2025-06-26">
  * Added: `getSubscriptions` endpoint that allows retrieving all of customers' subscriptions
</Update>

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

<Update label="2.293.0" description="2025-01-21">
  * Added: `ImportSubscriptionInput.subscription_id`
</Update>

<Update label="2.289.0" description="2025-01-19">
  * Added: `importSubscriptionInput.salesforce_id`, `importCustomerInput.salesforce_id`
</Update>

<Update label="2.235.0" description="2024-12-17">
  * Added: `get_usage_history_v_2`
  * ⚠️ Deprecated: `get_usage_history`(please use `get_usage_history_v_2` instead)
  * Changed:
    * Input Object:
      * `customer_ref_id` renamed to `customer_id`
      * `resource_ref_id` renamed to `resource_id`
      * `feature_ref_id` renamed to `feature_id`
      * `reset_period` removed
      * `yearly_reset_period_configuration` removed
      * `monthly_reset_period_configuration` removed
      * `weekly_reset_period_configuration` removed
    * Output Object
      * `start_date` removed
      * `end_date` removed
      * `usage.measurements[i].date` renamed to `series[0].point[i].timestamp`
      * `usage.measurements[i].value` renamed to `series[0].point[i].value`
      * `usage.measurements[i].is_reset_point` renamed to `series[0].point[i].is_reset_point`
        * 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].group_info[j].key` renamed to `series[i].tags[j].key`
      * `groups[i].group_info[j].value` renamed to `series[i].tags[j].value`
      * `groups[i].usage_measurements[j].date` renamed to `series[i].point[j].timestamp`
      * `groups[i].usage_measurements[j].value` renamed to `series[i].point[j].value`
      * `groups[i].usage_measurements[j].is_reset_point` renamed to `series[i].point[j].is_reset_point`
        * 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.
</Update>

<Update label="2.233.0" description="2024-12-15">
  * Added: `SlimSubscriptionFragmentV2.trial_configuration` and `SlimSubscriptionFragmentV2.trial_end_date`
</Update>

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

<Update label="2.212.4" description="2024-12-3">
  * Added: `TrialConfiguration` to `getActiveSubscriptions()`
</Update>

<Update label="2.212.1" description="2024-12-02">
  * Added: validation that coupon name does not exceed 40 characters
</Update>

<Update label="2.209.0" description="2024-12-02">
  * Added: `SubscriptionCouponDiscountInput.amounts_off`
  * Added: `SubscriptionCouponDiscountInput.description`
  * Added: `SubscriptionCouponDiscountInput.duration_in_months`
  * Added: `SubscriptionCouponDiscountInput.name`
  * Added: `SubscriptionCouponDiscountInput.percent_off`
</Update>

<Update label="2.207.0" description="2024-12-01">
  * Added: `EstimateSubscriptionInput.TrialOverrideConfigurationInput.trial_end_behavior`
  * Added: `PreviewSubscriptionInput.TrialOverrideConfigurationInput.trial_end_behavior`
</Update>

<Update label="2.204.0" description="2024-11-24">
  * Added: `EstimateSubscriptionInput.TrialOverrideConfigurationInput.trial_end_date`
  * Added: `PreviewSubscriptionInput.TrialOverrideConfigurationInput.trial_end_date`
</Update>

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

<Update label="2.196.1" description="2024-11-18">
  * Added: Ability to remove customer's email address by passing an empty string on `updateCustomerInput.email`
</Update>

<Update label="2.196.0" description="2024-11-18">
  * Added: `delegate_subscription_to_customer()`
  * Added: `transfer_subscription_to_resource()`
  * ⚠️ Deprecated: `transfer_subscription()` method (please use `transfer_subscription_to_resource()` instead)
</Update>

<Update label="2.188.0" description="2024-11-05">
  * Added: `UsageHistoryFragment.Markers`to reflect information about the reset usage dates
</Update>

<Update label="2.178.1" description="2024-11-04">
  * Fixed: issue where `customer.discount.deleted` event from Stripe isn't handled properly
</Update>

<Update label="2.175.4" description="2024-10-31">
  * Added: ability to set any date in the `SubscriptionFragment.trialEndDate`
</Update>

<Update label="2.162.0" description="2024-10-13">
  * Added: ability to estimate the subscription cost when the payment of the subscription is delegated to a different customer using:
    * `ProvisionSubscriptionInput.paying_customer_id`
    * `UpdateSubscriptionInput.paying_customer_id`
    * `ApplySubscriptionInput.paying_customer_id`
    * `PreviewSubscriptionInput.paying_customer_id`
    * `EstimateSubscriptionInput.paying_customer_id`
    * `EstimateSubscriptionUpdateInput.paying_customer_id`
</Update>

<Update label="2.160.0" description="2024-10-13">
  * Added: raise error when sync to Stripe fails due to unrecognized customer billing address
</Update>

<Update label="2.151.0" description="2024-10-06">
  * Added: ability to more easily determine the usage period of metered entitlements using:
    * `EntitlementFragment.usage_period_start`
    * `EntitlementFragment.usage_period_end`
  * ⚠️ Deprecated: `Entitlement.nextResetDate` field
</Update>

<Update label="2.131.1" description="2024-09-19">
  * Added: raise error when attempting to import a customer with an existing `billing_id`
</Update>

<Update label="2.129.0" description="2024-09-17">
  * Added: `CustomerPortalSubscriptionFragment.plan_id`
</Update>

<Update label="2.123.1" description="2024-09-11">
  * Added: `SubscriptionCouponInput.billing_coupon_id`
  * ⚠️ Deprecated: `ProvisionSubscriptionInput.promotion_code`
  * ⚠️ Deprecated: `UpdateSubscriptionInput.promotion_code`
  * ⚠️ Deprecated: `ApplySubscriptionInput.promotion_code`
  * ⚠️ Deprecated: `PreviewSubscriptionInput.promotion_code`
  * ⚠️ Deprecated: `EstimateSubscriptionInput.promotion_code`
  * ⚠️ Deprecated: `EstimateSubscriptionUpdateInput.promotion_code`
</Update>

<Update label="2.100.2" description="2024-09-01">
  * Added: ability to delegate payment of a provisioned subscription to a different customer using:
    * `ProvisionSubscriptionInput.paying_customer_id`
    * `ApplySubscriptionInput.paying_customer_id`
    * `SlimSubscriptionFragmentV2.payingCustomer`
    * `FullSubscription.payingCustomer`
</Update>

<Update label="2.86.0" description="2024-08-22">
  * Added: ability to apply a coupon to a subscription using the Stigg coupon ID using:
    * `ProvisionSubscriptionInput.applied_coupon`
    * `UpdateSubscriptionInput.applied_coupon`
    * `ApplySubscriptionInput.applied_coupon`
    * `PreviewSubscriptionInput.applied_coupon`
    * `EstimateSubscriptionInput.applied_coupon`
    * `EstimateSubscriptionUpdateInput.applied_coupon`
</Update>

<Update label="2.80.2" description="2024-08-20">
  * Changed: `ImportCustomerBulk` changed to `ImportCustomerBulkInput`
</Update>

<Update label="2.62.4" description="2024-08-07">
  * Added: ability to undo subscription scheduled cancelation using`cancel_subscription_updates()`
</Update>

<Update label="2.62.0" description="2024-08-07">
  * Added: ability to preview a subscription's upcoming invoice using`preview_next_invoice()`
</Update>

<Update label="2.20.0" description="2024-07-07">
  * Changed: `fetch_usage_history()` now returns the precise timestamp when the usage was reset
</Update>

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

<Update label="2.8.2" description="2024-06-27">
  * Added: `TrialOverrideConfigurationInput.trial_end_date` to allow scheduled trial cancelation when provisioning and updating subscriptions
</Update>

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

<Update label="1.232.0" description="2024-06-16">
  * Added: ability to get the list of active subscriptions using `get_active_subscriptions()`
</Update>

<Update label="1.0.0" description="2024-01-22">
  🛑 Breaking change

  * Changed: For Volume/tiered pricing, `unit_price` was moved to `flat_price`.
</Update>