orb-billing 1.24.0 → 1.26.0

data/rbi/orb/resources/alerts.rbi

@@ -18,7 +18,10 @@ module Orb
       def retrieve(alert_id, request_options: {})
       end
 
-      # This endpoint updates the thresholds of an alert.
+      # This endpoint updates the thresholds of an alert. On cost alerts it also updates
+      # `price_filters`, and on subscription-scoped grouped cost alerts
+      # `threshold_overrides`; omitting either leaves it unchanged, and an empty list
+      # clears it.
       sig do
         params(
           alert_configuration_id: String,
@@ -36,8 +39,10 @@ module Orb
         alert_configuration_id,
         # The thresholds that define the values at which the alert will be triggered.
         thresholds:,
-        # Replaces the price filters on a grouped cost alert; an empty list clears them.
-        # Only applicable to cost alerts with grouping_keys. Omit to leave unchanged.
+        # Replaces the price filters on the alert; an empty list clears them. Only
+        # applicable to spend_exceeded alerts and to cost_exceeded alerts with
+        # grouping_keys set. Alerts accept the price_id, item_id, and price_type fields
+        # only. Omit to leave unchanged.
         price_filters: nil,
         # Replaces the per-group threshold overrides on a grouped cost alert; an empty
         # list clears them. Only applicable to cost alerts with grouping_keys. Omit to

data/rbi/orb/resources/customers/costs.rbi

@@ -139,6 +139,16 @@ module Orb
         # matrix dimensions. Orb will return `price_groups` with the `grouping_key` and
         # `secondary_grouping_key` based on the matrix price definition, for each
         # `grouping_value` and `secondary_grouping_value` available.
+        #
+        # ## Trials
+        #
+        # During a trial, usage prices carry a trial discount, capped at the plan's trial
+        # maximum amount (or 100% when no maximum is set), and the trial period is billed
+        # as a single invoice dated at the trial's end. In the costs response,
+        # trial-period usage appears at full list price in `subtotal`, with the trial
+        # discount reflected in `total`: `total` is \$0 as long as usage stays within the
+        # trial maximum, and usage beyond the maximum bills normally. Fixed fees are not
+        # charged during a trial.
         sig do
           params(
             customer_id: String,
@@ -284,6 +294,16 @@ module Orb
         # matrix dimensions. Orb will return `price_groups` with the `grouping_key` and
         # `secondary_grouping_key` based on the matrix price definition, for each
         # `grouping_value` and `secondary_grouping_value` available.
+        #
+        # ## Trials
+        #
+        # During a trial, usage prices carry a trial discount, capped at the plan's trial
+        # maximum amount (or 100% when no maximum is set), and the trial period is billed
+        # as a single invoice dated at the trial's end. In the costs response,
+        # trial-period usage appears at full list price in `subtotal`, with the trial
+        # discount reflected in `total`: `total` is \$0 as long as usage stays within the
+        # trial maximum, and usage beyond the maximum bills normally. Fixed fees are not
+        # charged during a trial.
         sig do
           params(
             external_customer_id: String,

data/rbi/orb/resources/licenses/external_licenses.rbi

@@ -7,6 +7,13 @@ module Orb
         # Returns usage and remaining credits for a license identified by its external
         # license ID.
         #
+        # Resolves the currently active license with this external ID, i.e. the license
+        # whose active window contains the current time. An external license ID can map to
+        # multiple licenses over time, so if none is currently active (deactivated, window
+        # ended, or not yet started) this returns a 404. To fetch usage for a license
+        # regardless of active state, use the endpoint that takes Orb's internal license
+        # ID.
+        #
         # Date range defaults to the current billing period if not specified.
         sig do
           params(

data/rbi/orb/resources/licenses/usage.rbi

@@ -44,6 +44,9 @@ module Orb
 
         # Returns usage and remaining credits for a specific license over a date range.
         #
+        # Resolves the license by ID regardless of whether it is currently active, unlike
+        # the external-license-ID variant, which only resolves a currently active license.
+        #
         # Date range defaults to the current billing period if not specified.
         sig do
           params(

data/rbi/orb/resources/prices.rbi

@@ -50,6 +50,7 @@ module Orb
               Orb::NewFloatingTieredPackagePrice::OrHash,
               Orb::NewFloatingTieredWithMinimumPrice::OrHash,
               Orb::NewFloatingGroupedTieredPrice::OrHash,
+              Orb::PriceCreateParams::Body::GroupedTieredMatrix::OrHash,
               Orb::NewFloatingTieredPackageWithMinimumPrice::OrHash,
               Orb::NewFloatingPackageWithAllocationPrice::OrHash,
               Orb::NewFloatingUnitWithPercentPrice::OrHash,

data/rbi/orb/resources/subscriptions.rbi

@@ -1103,6 +1103,17 @@ module Orb
       # Note that one of `plan_id` or `external_plan_id` is required in the request body
       # for this operation.
       #
+      # ## Interaction with scheduled cancellations
+      #
+      # Scheduling a plan change also unschedules a pending cancellation, as long as the
+      # cancellation date is on or after the plan change date: Orb honors the plan
+      # change over the scheduled cancellation, and the subscription continues on the
+      # new plan. Scheduling a plan change after the subscription's end date returns a
+      # validation error instead.
+      #
+      # Any plan changes already scheduled at or after the new plan change's date are
+      # unscheduled and replaced by it.
+      #
       # ## Customize your customer's subscriptions
       #
       # Prices and adjustments in a plan can be added, removed, or replaced on the
@@ -1439,11 +1450,19 @@ module Orb
       # cancellation. This operation will turn on auto-renew, ensuring that the
       # subscription does not end at the currently scheduled cancellation time.
       #
-      # Note: uncancellation is a lossy operation. Price intervals that were cut short
-      # by the cancellation are extended to infinity (original end dates are lost), and
-      # future intervals or phases scheduled after the cancellation time are permanently
-      # deleted. For complex subscriptions with phases or scheduled plan changes,
-      # consider creating a new plan change instead of uncancelling.
+      # A cancellation that has already taken effect cannot be unscheduled. This
+      # includes backdated cancellations: once the subscription's end date is in the
+      # past, this endpoint returns a validation error.
+      #
+      # Note: uncancellation is a lossy operation. Price and adjustment intervals that
+      # were cut short by the cancellation are extended to infinity (original end dates
+      # are lost), and future intervals or phases scheduled after the cancellation time
+      # are permanently deleted. For complex subscriptions with phases or scheduled plan
+      # changes, consider creating a new plan change instead of uncancelling.
+      #
+      # If the scheduled cancellation already produced invoices or credit notes (for
+      # example, a proration refund credit note for an in-advance fee), uncancelling
+      # voids and reissues them as needed to match the subscription's new state.
       sig do
         params(
           subscription_id: String,
@@ -1474,7 +1493,21 @@ module Orb
       end
 
       # This endpoint can be used to unschedule any pending plan changes on an existing
-      # subscription. When called, all upcoming plan changes will be unscheduled.
+      # subscription. When called, all upcoming plan changes will be unscheduled; it is
+      # not possible to unschedule a single plan change if multiple are scheduled.
+      #
+      # Note: unscheduling a plan change is a lossy operation, with the same semantics
+      # as
+      # [unscheduling a cancellation](/api-reference/subscription/unschedule-subscription-cancellation).
+      # Prices and adjustments on the current plan that were scheduled to end at the
+      # plan change time are extended to infinity (original end dates are lost), and
+      # anything scheduled to start after the plan change time is permanently deleted.
+      # Coupons redeemed as part of an unscheduled plan change are released and can be
+      # redeemed again.
+      #
+      # A scheduled cancellation is not affected by this operation: if the subscription
+      # has both a pending plan change and a scheduled cancellation, unscheduling the
+      # plan change leaves the cancellation in place.
       sig do
         params(
           subscription_id: String,

data/sig/orb/models/beta/external_plan_id_create_plan_version_params.rbs

@@ -475,6 +475,7 @@ module Orb
             | Orb::NewPlanTieredPackagePrice
             | Orb::NewPlanTieredWithMinimumPrice
             | Orb::NewPlanGroupedTieredPrice
+            | Orb::Beta::ExternalPlanIDCreatePlanVersionParams::AddPrice::Price::GroupedTieredMatrix
             | Orb::NewPlanTieredPackageWithMinimumPrice
             | Orb::NewPlanPackageWithAllocationPrice
             | Orb::NewPlanUnitWithPercentPrice
@@ -689,6 +690,188 @@ module Orb
               end
             end
 
+            type grouped_tiered_matrix =
+              {
+                cadence: Orb::Models::Beta::ExternalPlanIDCreatePlanVersionParams::AddPrice::Price::GroupedTieredMatrix::cadence,
+                grouped_tiered_matrix_config: Orb::Beta::ExternalPlanIDCreatePlanVersionParams::AddPrice::Price::GroupedTieredMatrix::GroupedTieredMatrixConfig,
+                item_id: String,
+                model_type: :grouped_tiered_matrix,
+                name: String,
+                billable_metric_id: String?,
+                billed_in_advance: bool?,
+                billing_cycle_configuration: Orb::NewBillingCycleConfiguration?,
+                conversion_rate: Float?,
+                conversion_rate_config: Orb::Models::conversion_rate_config?,
+                currency: String?,
+                dimensional_price_configuration: Orb::NewDimensionalPriceConfiguration?,
+                external_price_id: String?,
+                fixed_price_quantity: Float?,
+                invoice_grouping_key: String?,
+                invoicing_cycle_configuration: Orb::NewBillingCycleConfiguration?,
+                license_type_id: String?,
+                metadata: ::Hash[Symbol, String?]?,
+                reference_id: String?
+              }
+
+            class GroupedTieredMatrix < Orb::Internal::Type::BaseModel
+              attr_accessor cadence: Orb::Models::Beta::ExternalPlanIDCreatePlanVersionParams::AddPrice::Price::GroupedTieredMatrix::cadence
+
+              attr_accessor grouped_tiered_matrix_config: Orb::Beta::ExternalPlanIDCreatePlanVersionParams::AddPrice::Price::GroupedTieredMatrix::GroupedTieredMatrixConfig
+
+              attr_accessor item_id: String
+
+              attr_accessor model_type: :grouped_tiered_matrix
+
+              attr_accessor name: String
+
+              attr_accessor billable_metric_id: String?
+
+              attr_accessor billed_in_advance: bool?
+
+              attr_accessor billing_cycle_configuration: Orb::NewBillingCycleConfiguration?
+
+              attr_accessor conversion_rate: Float?
+
+              attr_accessor conversion_rate_config: Orb::Models::conversion_rate_config?
+
+              attr_accessor currency: String?
+
+              attr_accessor dimensional_price_configuration: Orb::NewDimensionalPriceConfiguration?
+
+              attr_accessor external_price_id: String?
+
+              attr_accessor fixed_price_quantity: Float?
+
+              attr_accessor invoice_grouping_key: String?
+
+              attr_accessor invoicing_cycle_configuration: Orb::NewBillingCycleConfiguration?
+
+              attr_accessor license_type_id: String?
+
+              attr_accessor metadata: ::Hash[Symbol, String?]?
+
+              attr_accessor reference_id: String?
+
+              def initialize: (
+                cadence: Orb::Models::Beta::ExternalPlanIDCreatePlanVersionParams::AddPrice::Price::GroupedTieredMatrix::cadence,
+                grouped_tiered_matrix_config: Orb::Beta::ExternalPlanIDCreatePlanVersionParams::AddPrice::Price::GroupedTieredMatrix::GroupedTieredMatrixConfig,
+                item_id: String,
+                name: String,
+                ?billable_metric_id: String?,
+                ?billed_in_advance: bool?,
+                ?billing_cycle_configuration: Orb::NewBillingCycleConfiguration?,
+                ?conversion_rate: Float?,
+                ?conversion_rate_config: Orb::Models::conversion_rate_config?,
+                ?currency: String?,
+                ?dimensional_price_configuration: Orb::NewDimensionalPriceConfiguration?,
+                ?external_price_id: String?,
+                ?fixed_price_quantity: Float?,
+                ?invoice_grouping_key: String?,
+                ?invoicing_cycle_configuration: Orb::NewBillingCycleConfiguration?,
+                ?license_type_id: String?,
+                ?metadata: ::Hash[Symbol, String?]?,
+                ?reference_id: String?,
+                ?model_type: :grouped_tiered_matrix
+              ) -> void
+
+              def to_hash: -> {
+                cadence: Orb::Models::Beta::ExternalPlanIDCreatePlanVersionParams::AddPrice::Price::GroupedTieredMatrix::cadence,
+                grouped_tiered_matrix_config: Orb::Beta::ExternalPlanIDCreatePlanVersionParams::AddPrice::Price::GroupedTieredMatrix::GroupedTieredMatrixConfig,
+                item_id: String,
+                model_type: :grouped_tiered_matrix,
+                name: String,
+                billable_metric_id: String?,
+                billed_in_advance: bool?,
+                billing_cycle_configuration: Orb::NewBillingCycleConfiguration?,
+                conversion_rate: Float?,
+                conversion_rate_config: Orb::Models::conversion_rate_config?,
+                currency: String?,
+                dimensional_price_configuration: Orb::NewDimensionalPriceConfiguration?,
+                external_price_id: String?,
+                fixed_price_quantity: Float?,
+                invoice_grouping_key: String?,
+                invoicing_cycle_configuration: Orb::NewBillingCycleConfiguration?,
+                license_type_id: String?,
+                metadata: ::Hash[Symbol, String?]?,
+                reference_id: String?
+              }
+
+              type cadence =
+                :annual
+                | :semi_annual
+                | :monthly
+                | :quarterly
+                | :one_time
+                | :custom
+
+              module Cadence
+                extend Orb::Internal::Type::Enum
+
+                ANNUAL: :annual
+                SEMI_ANNUAL: :semi_annual
+                MONTHLY: :monthly
+                QUARTERLY: :quarterly
+                ONE_TIME: :one_time
+                CUSTOM: :custom
+
+                def self?.values: -> ::Array[Orb::Models::Beta::ExternalPlanIDCreatePlanVersionParams::AddPrice::Price::GroupedTieredMatrix::cadence]
+              end
+
+              type grouped_tiered_matrix_config =
+                {
+                  default_unit_amount: String,
+                  dimension: String,
+                  tiers: ::Array[Orb::Beta::ExternalPlanIDCreatePlanVersionParams::AddPrice::Price::GroupedTieredMatrix::GroupedTieredMatrixConfig::Tier]
+                }
+
+              class GroupedTieredMatrixConfig < Orb::Internal::Type::BaseModel
+                attr_accessor default_unit_amount: String
+
+                attr_accessor dimension: String
+
+                attr_accessor tiers: ::Array[Orb::Beta::ExternalPlanIDCreatePlanVersionParams::AddPrice::Price::GroupedTieredMatrix::GroupedTieredMatrixConfig::Tier]
+
+                def initialize: (
+                  default_unit_amount: String,
+                  dimension: String,
+                  tiers: ::Array[Orb::Beta::ExternalPlanIDCreatePlanVersionParams::AddPrice::Price::GroupedTieredMatrix::GroupedTieredMatrixConfig::Tier]
+                ) -> void
+
+                def to_hash: -> {
+                  default_unit_amount: String,
+                  dimension: String,
+                  tiers: ::Array[Orb::Beta::ExternalPlanIDCreatePlanVersionParams::AddPrice::Price::GroupedTieredMatrix::GroupedTieredMatrixConfig::Tier]
+                }
+
+                type tier =
+                  {
+                    dimension_value: String,
+                    tier_lower_bound: String,
+                    unit_amount: String
+                  }
+
+                class Tier < Orb::Internal::Type::BaseModel
+                  attr_accessor dimension_value: String
+
+                  attr_accessor tier_lower_bound: String
+
+                  attr_accessor unit_amount: String
+
+                  def initialize: (
+                    dimension_value: String,
+                    tier_lower_bound: String,
+                    unit_amount: String
+                  ) -> void
+
+                  def to_hash: -> {
+                    dimension_value: String,
+                    tier_lower_bound: String,
+                    unit_amount: String
+                  }
+                end
+              end
+            end
+
             type matrix_with_threshold_discounts =
               {
                 cadence: Orb::Models::Beta::ExternalPlanIDCreatePlanVersionParams::AddPrice::Price::MatrixWithThresholdDiscounts::cadence,
@@ -2537,6 +2720,7 @@ module Orb
             | Orb::NewPlanTieredPackagePrice
             | Orb::NewPlanTieredWithMinimumPrice
             | Orb::NewPlanGroupedTieredPrice
+            | Orb::Beta::ExternalPlanIDCreatePlanVersionParams::ReplacePrice::Price::GroupedTieredMatrix
             | Orb::NewPlanTieredPackageWithMinimumPrice
             | Orb::NewPlanPackageWithAllocationPrice
             | Orb::NewPlanUnitWithPercentPrice
@@ -2751,6 +2935,188 @@ module Orb
               end
             end
 
+            type grouped_tiered_matrix =
+              {
+                cadence: Orb::Models::Beta::ExternalPlanIDCreatePlanVersionParams::ReplacePrice::Price::GroupedTieredMatrix::cadence,
+                grouped_tiered_matrix_config: Orb::Beta::ExternalPlanIDCreatePlanVersionParams::ReplacePrice::Price::GroupedTieredMatrix::GroupedTieredMatrixConfig,
+                item_id: String,
+                model_type: :grouped_tiered_matrix,
+                name: String,
+                billable_metric_id: String?,
+                billed_in_advance: bool?,
+                billing_cycle_configuration: Orb::NewBillingCycleConfiguration?,
+                conversion_rate: Float?,
+                conversion_rate_config: Orb::Models::conversion_rate_config?,
+                currency: String?,
+                dimensional_price_configuration: Orb::NewDimensionalPriceConfiguration?,
+                external_price_id: String?,
+                fixed_price_quantity: Float?,
+                invoice_grouping_key: String?,
+                invoicing_cycle_configuration: Orb::NewBillingCycleConfiguration?,
+                license_type_id: String?,
+                metadata: ::Hash[Symbol, String?]?,
+                reference_id: String?
+              }
+
+            class GroupedTieredMatrix < Orb::Internal::Type::BaseModel
+              attr_accessor cadence: Orb::Models::Beta::ExternalPlanIDCreatePlanVersionParams::ReplacePrice::Price::GroupedTieredMatrix::cadence
+
+              attr_accessor grouped_tiered_matrix_config: Orb::Beta::ExternalPlanIDCreatePlanVersionParams::ReplacePrice::Price::GroupedTieredMatrix::GroupedTieredMatrixConfig
+
+              attr_accessor item_id: String
+
+              attr_accessor model_type: :grouped_tiered_matrix
+
+              attr_accessor name: String
+
+              attr_accessor billable_metric_id: String?
+
+              attr_accessor billed_in_advance: bool?
+
+              attr_accessor billing_cycle_configuration: Orb::NewBillingCycleConfiguration?
+
+              attr_accessor conversion_rate: Float?
+
+              attr_accessor conversion_rate_config: Orb::Models::conversion_rate_config?
+
+              attr_accessor currency: String?
+
+              attr_accessor dimensional_price_configuration: Orb::NewDimensionalPriceConfiguration?
+
+              attr_accessor external_price_id: String?
+
+              attr_accessor fixed_price_quantity: Float?
+
+              attr_accessor invoice_grouping_key: String?
+
+              attr_accessor invoicing_cycle_configuration: Orb::NewBillingCycleConfiguration?
+
+              attr_accessor license_type_id: String?
+
+              attr_accessor metadata: ::Hash[Symbol, String?]?
+
+              attr_accessor reference_id: String?
+
+              def initialize: (
+                cadence: Orb::Models::Beta::ExternalPlanIDCreatePlanVersionParams::ReplacePrice::Price::GroupedTieredMatrix::cadence,
+                grouped_tiered_matrix_config: Orb::Beta::ExternalPlanIDCreatePlanVersionParams::ReplacePrice::Price::GroupedTieredMatrix::GroupedTieredMatrixConfig,
+                item_id: String,
+                name: String,
+                ?billable_metric_id: String?,
+                ?billed_in_advance: bool?,
+                ?billing_cycle_configuration: Orb::NewBillingCycleConfiguration?,
+                ?conversion_rate: Float?,
+                ?conversion_rate_config: Orb::Models::conversion_rate_config?,
+                ?currency: String?,
+                ?dimensional_price_configuration: Orb::NewDimensionalPriceConfiguration?,
+                ?external_price_id: String?,
+                ?fixed_price_quantity: Float?,
+                ?invoice_grouping_key: String?,
+                ?invoicing_cycle_configuration: Orb::NewBillingCycleConfiguration?,
+                ?license_type_id: String?,
+                ?metadata: ::Hash[Symbol, String?]?,
+                ?reference_id: String?,
+                ?model_type: :grouped_tiered_matrix
+              ) -> void
+
+              def to_hash: -> {
+                cadence: Orb::Models::Beta::ExternalPlanIDCreatePlanVersionParams::ReplacePrice::Price::GroupedTieredMatrix::cadence,
+                grouped_tiered_matrix_config: Orb::Beta::ExternalPlanIDCreatePlanVersionParams::ReplacePrice::Price::GroupedTieredMatrix::GroupedTieredMatrixConfig,
+                item_id: String,
+                model_type: :grouped_tiered_matrix,
+                name: String,
+                billable_metric_id: String?,
+                billed_in_advance: bool?,
+                billing_cycle_configuration: Orb::NewBillingCycleConfiguration?,
+                conversion_rate: Float?,
+                conversion_rate_config: Orb::Models::conversion_rate_config?,
+                currency: String?,
+                dimensional_price_configuration: Orb::NewDimensionalPriceConfiguration?,
+                external_price_id: String?,
+                fixed_price_quantity: Float?,
+                invoice_grouping_key: String?,
+                invoicing_cycle_configuration: Orb::NewBillingCycleConfiguration?,
+                license_type_id: String?,
+                metadata: ::Hash[Symbol, String?]?,
+                reference_id: String?
+              }
+
+              type cadence =
+                :annual
+                | :semi_annual
+                | :monthly
+                | :quarterly
+                | :one_time
+                | :custom
+
+              module Cadence
+                extend Orb::Internal::Type::Enum
+
+                ANNUAL: :annual
+                SEMI_ANNUAL: :semi_annual
+                MONTHLY: :monthly
+                QUARTERLY: :quarterly
+                ONE_TIME: :one_time
+                CUSTOM: :custom
+
+                def self?.values: -> ::Array[Orb::Models::Beta::ExternalPlanIDCreatePlanVersionParams::ReplacePrice::Price::GroupedTieredMatrix::cadence]
+              end
+
+              type grouped_tiered_matrix_config =
+                {
+                  default_unit_amount: String,
+                  dimension: String,
+                  tiers: ::Array[Orb::Beta::ExternalPlanIDCreatePlanVersionParams::ReplacePrice::Price::GroupedTieredMatrix::GroupedTieredMatrixConfig::Tier]
+                }
+
+              class GroupedTieredMatrixConfig < Orb::Internal::Type::BaseModel
+                attr_accessor default_unit_amount: String
+
+                attr_accessor dimension: String
+
+                attr_accessor tiers: ::Array[Orb::Beta::ExternalPlanIDCreatePlanVersionParams::ReplacePrice::Price::GroupedTieredMatrix::GroupedTieredMatrixConfig::Tier]
+
+                def initialize: (
+                  default_unit_amount: String,
+                  dimension: String,
+                  tiers: ::Array[Orb::Beta::ExternalPlanIDCreatePlanVersionParams::ReplacePrice::Price::GroupedTieredMatrix::GroupedTieredMatrixConfig::Tier]
+                ) -> void
+
+                def to_hash: -> {
+                  default_unit_amount: String,
+                  dimension: String,
+                  tiers: ::Array[Orb::Beta::ExternalPlanIDCreatePlanVersionParams::ReplacePrice::Price::GroupedTieredMatrix::GroupedTieredMatrixConfig::Tier]
+                }
+
+                type tier =
+                  {
+                    dimension_value: String,
+                    tier_lower_bound: String,
+                    unit_amount: String
+                  }
+
+                class Tier < Orb::Internal::Type::BaseModel
+                  attr_accessor dimension_value: String
+
+                  attr_accessor tier_lower_bound: String
+
+                  attr_accessor unit_amount: String
+
+                  def initialize: (
+                    dimension_value: String,
+                    tier_lower_bound: String,
+                    unit_amount: String
+                  ) -> void
+
+                  def to_hash: -> {
+                    dimension_value: String,
+                    tier_lower_bound: String,
+                    unit_amount: String
+                  }
+                end
+              end
+            end
+
             type matrix_with_threshold_discounts =
               {
                 cadence: Orb::Models::Beta::ExternalPlanIDCreatePlanVersionParams::ReplacePrice::Price::MatrixWithThresholdDiscounts::cadence,