orb-billing 6.8.0 → 6.10.0

package/src/resources/invoices.ts

@@ -730,9 +730,9 @@ export namespace InvoiceFetchUpcomingResponse {
      * If Orb has ever attempted payment auto-collection for this invoice, this field
      * will reflect when that attempt occurred. In conjunction with `next_attempt_at`,
      * this can be used to tell whether the invoice is currently in dunning (that is,
-     * `previously_attempted_at` is non-null, and `next_attempt_time` is non-null), or
-     * if dunning has been exhausted (`previously_attempted_at` is non-null, but
-     * `next_attempt_time` is null).
+     * `previously_attempted_at` is non-null, and `next_attempt_at` is non-null), or if
+     * dunning has been exhausted (`previously_attempted_at` is non-null, but
+     * `next_attempt_at` is null).
      */
     previously_attempted_at: string | null;
   }
@@ -1389,9 +1389,9 @@ export namespace InvoiceIssueSummaryResponse {
      * If Orb has ever attempted payment auto-collection for this invoice, this field
      * will reflect when that attempt occurred. In conjunction with `next_attempt_at`,
      * this can be used to tell whether the invoice is currently in dunning (that is,
-     * `previously_attempted_at` is non-null, and `next_attempt_time` is non-null), or
-     * if dunning has been exhausted (`previously_attempted_at` is non-null, but
-     * `next_attempt_time` is null).
+     * `previously_attempted_at` is non-null, and `next_attempt_at` is non-null), or if
+     * dunning has been exhausted (`previously_attempted_at` is non-null, but
+     * `next_attempt_at` is null).
      */
     previously_attempted_at: string | null;
   }
@@ -1846,9 +1846,9 @@ export namespace InvoiceListSummaryResponse {
      * If Orb has ever attempted payment auto-collection for this invoice, this field
      * will reflect when that attempt occurred. In conjunction with `next_attempt_at`,
      * this can be used to tell whether the invoice is currently in dunning (that is,
-     * `previously_attempted_at` is non-null, and `next_attempt_time` is non-null), or
-     * if dunning has been exhausted (`previously_attempted_at` is non-null, but
-     * `next_attempt_time` is null).
+     * `previously_attempted_at` is non-null, and `next_attempt_at` is non-null), or if
+     * dunning has been exhausted (`previously_attempted_at` is non-null, but
+     * `next_attempt_at` is null).
      */
     previously_attempted_at: string | null;
   }

package/src/resources/licenses/external-licenses.ts

@@ -11,6 +11,13 @@ export class ExternalLicenses extends APIResource {
    * 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.
    *
    * @example

package/src/resources/licenses/usage.ts

@@ -28,6 +28,9 @@ export class Usage extends APIResource {
   /**
    * 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.
    *
    * @example

package/src/resources/plans/plans.ts

@@ -454,6 +454,7 @@ export namespace PlanCreateParams {
       | Shared.NewPlanTieredPackagePrice
       | Shared.NewPlanTieredWithMinimumPrice
       | Shared.NewPlanGroupedTieredPrice
+      | Price.NewPlanGroupedTieredMatrixPrice
       | Shared.NewPlanTieredPackageWithMinimumPrice
       | Shared.NewPlanPackageWithAllocationPrice
       | Shared.NewPlanUnitWithPercentPrice
@@ -772,6 +773,154 @@ export namespace PlanCreateParams {
       }
     }
 
+    export interface NewPlanGroupedTieredMatrixPrice {
+      /**
+       * The cadence to bill for this price on.
+       */
+      cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time' | 'custom';
+
+      /**
+       * Configuration for grouped_tiered_matrix pricing
+       */
+      grouped_tiered_matrix_config: NewPlanGroupedTieredMatrixPrice.GroupedTieredMatrixConfig;
+
+      /**
+       * The id of the item the price will be associated with.
+       */
+      item_id: string;
+
+      /**
+       * The pricing model type
+       */
+      model_type: 'grouped_tiered_matrix';
+
+      /**
+       * The name of the price.
+       */
+      name: string;
+
+      /**
+       * The id of the billable metric for the price. Only needed if the price is
+       * usage-based.
+       */
+      billable_metric_id?: string | null;
+
+      /**
+       * If the Price represents a fixed cost, the price will be billed in-advance if
+       * this is true, and in-arrears if this is false.
+       */
+      billed_in_advance?: boolean | null;
+
+      /**
+       * For custom cadence: specifies the duration of the billing period in days or
+       * months.
+       */
+      billing_cycle_configuration?: Shared.NewBillingCycleConfiguration | null;
+
+      /**
+       * The per unit conversion rate of the price currency to the invoicing currency.
+       */
+      conversion_rate?: number | null;
+
+      /**
+       * The configuration for the rate of the price currency to the invoicing currency.
+       */
+      conversion_rate_config?: Shared.UnitConversionRateConfig | Shared.TieredConversionRateConfig | null;
+
+      /**
+       * An ISO 4217 currency string, or custom pricing unit identifier, in which this
+       * price is billed.
+       */
+      currency?: string | null;
+
+      /**
+       * For dimensional price: specifies a price group and dimension values
+       */
+      dimensional_price_configuration?: Shared.NewDimensionalPriceConfiguration | null;
+
+      /**
+       * An alias for the price.
+       */
+      external_price_id?: string | null;
+
+      /**
+       * If the Price represents a fixed cost, this represents the quantity of units
+       * applied.
+       */
+      fixed_price_quantity?: number | null;
+
+      /**
+       * The property used to group this price on an invoice
+       */
+      invoice_grouping_key?: string | null;
+
+      /**
+       * Within each billing cycle, specifies the cadence at which invoices are produced.
+       * If unspecified, a single invoice is produced per billing cycle.
+       */
+      invoicing_cycle_configuration?: Shared.NewBillingCycleConfiguration | null;
+
+      /**
+       * The ID of the license type to associate with this price.
+       */
+      license_type_id?: string | null;
+
+      /**
+       * User-specified key/value pairs for the resource. Individual keys can be removed
+       * by setting the value to `null`, and the entire metadata mapping can be cleared
+       * by setting `metadata` to `null`.
+       */
+      metadata?: { [key: string]: string | null } | null;
+
+      /**
+       * A transient ID that can be used to reference this price when adding adjustments
+       * in the same API call.
+       */
+      reference_id?: string | null;
+    }
+
+    export namespace NewPlanGroupedTieredMatrixPrice {
+      /**
+       * Configuration for grouped_tiered_matrix pricing
+       */
+      export interface GroupedTieredMatrixConfig {
+        /**
+         * Per unit rate for usage whose dimension value has no configured tiers
+         */
+        default_unit_amount: string;
+
+        /**
+         * The billable metric property used to group usage before tiering
+         */
+        dimension: string;
+
+        /**
+         * Graduated tiers keyed by dimension value; usage for a value is tiered only
+         * against its own rows
+         */
+        tiers: Array<GroupedTieredMatrixConfig.Tier>;
+      }
+
+      export namespace GroupedTieredMatrixConfig {
+        /**
+         * Configuration for a single tier scoped to a dimension value
+         */
+        export interface Tier {
+          /**
+           * The dimension value this tier applies to
+           */
+          dimension_value: string;
+
+          tier_lower_bound: string;
+
+          /**
+           * Per unit amount
+           */
+          unit_amount: string;
+        }
+      }
+    }
+
     export interface NewPlanMatrixWithThresholdDiscountsPrice {
       /**
        * The cadence to bill for this price on.

package/src/resources/prices/prices.ts

@@ -319,6 +319,7 @@ export type PriceCreateParams =
   | PriceCreateParams.NewFloatingTieredPackagePrice
   | PriceCreateParams.NewFloatingTieredWithMinimumPrice
   | PriceCreateParams.NewFloatingGroupedTieredPrice
+  | PriceCreateParams.NewFloatingGroupedTieredMatrixPrice
   | PriceCreateParams.NewFloatingTieredPackageWithMinimumPrice
   | PriceCreateParams.NewFloatingPackageWithAllocationPrice
   | PriceCreateParams.NewFloatingUnitWithPercentPrice
@@ -1518,6 +1519,147 @@ export declare namespace PriceCreateParams {
     }
   }
 
+  export interface NewFloatingGroupedTieredMatrixPrice {
+    /**
+     * The cadence to bill for this price on.
+     */
+    cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time' | 'custom';
+
+    /**
+     * An ISO 4217 currency string for which this price is billed in.
+     */
+    currency: string;
+
+    /**
+     * Configuration for grouped_tiered_matrix pricing
+     */
+    grouped_tiered_matrix_config: NewFloatingGroupedTieredMatrixPrice.GroupedTieredMatrixConfig;
+
+    /**
+     * The id of the item the price will be associated with.
+     */
+    item_id: string;
+
+    /**
+     * The pricing model type
+     */
+    model_type: 'grouped_tiered_matrix';
+
+    /**
+     * The name of the price.
+     */
+    name: string;
+
+    /**
+     * The id of the billable metric for the price. Only needed if the price is
+     * usage-based.
+     */
+    billable_metric_id?: string | null;
+
+    /**
+     * If the Price represents a fixed cost, the price will be billed in-advance if
+     * this is true, and in-arrears if this is false.
+     */
+    billed_in_advance?: boolean | null;
+
+    /**
+     * For custom cadence: specifies the duration of the billing period in days or
+     * months.
+     */
+    billing_cycle_configuration?: Shared.NewBillingCycleConfiguration | null;
+
+    /**
+     * The per unit conversion rate of the price currency to the invoicing currency.
+     */
+    conversion_rate?: number | null;
+
+    /**
+     * The configuration for the rate of the price currency to the invoicing currency.
+     */
+    conversion_rate_config?: Shared.UnitConversionRateConfig | Shared.TieredConversionRateConfig | null;
+
+    /**
+     * For dimensional price: specifies a price group and dimension values
+     */
+    dimensional_price_configuration?: Shared.NewDimensionalPriceConfiguration | null;
+
+    /**
+     * An alias for the price.
+     */
+    external_price_id?: string | null;
+
+    /**
+     * If the Price represents a fixed cost, this represents the quantity of units
+     * applied.
+     */
+    fixed_price_quantity?: number | null;
+
+    /**
+     * The property used to group this price on an invoice
+     */
+    invoice_grouping_key?: string | null;
+
+    /**
+     * Within each billing cycle, specifies the cadence at which invoices are produced.
+     * If unspecified, a single invoice is produced per billing cycle.
+     */
+    invoicing_cycle_configuration?: Shared.NewBillingCycleConfiguration | null;
+
+    /**
+     * The ID of the license type to associate with this price.
+     */
+    license_type_id?: string | null;
+
+    /**
+     * User-specified key/value pairs for the resource. Individual keys can be removed
+     * by setting the value to `null`, and the entire metadata mapping can be cleared
+     * by setting `metadata` to `null`.
+     */
+    metadata?: { [key: string]: string | null } | null;
+  }
+
+  export namespace NewFloatingGroupedTieredMatrixPrice {
+    /**
+     * Configuration for grouped_tiered_matrix pricing
+     */
+    export interface GroupedTieredMatrixConfig {
+      /**
+       * Per unit rate for usage whose dimension value has no configured tiers
+       */
+      default_unit_amount: string;
+
+      /**
+       * The billable metric property used to group usage before tiering
+       */
+      dimension: string;
+
+      /**
+       * Graduated tiers keyed by dimension value; usage for a value is tiered only
+       * against its own rows
+       */
+      tiers: Array<GroupedTieredMatrixConfig.Tier>;
+    }
+
+    export namespace GroupedTieredMatrixConfig {
+      /**
+       * Configuration for a single tier scoped to a dimension value
+       */
+      export interface Tier {
+        /**
+         * The dimension value this tier applies to
+         */
+        dimension_value: string;
+
+        tier_lower_bound: string;
+
+        /**
+         * Per unit amount
+         */
+        unit_amount: string;
+      }
+    }
+  }
+
   export interface NewFloatingTieredPackageWithMinimumPrice {
     /**
      * The cadence to bill for this price on.
@@ -4772,6 +4914,7 @@ export namespace PriceEvaluateMultipleParams {
       | Shared.NewFloatingTieredPackagePrice
       | Shared.NewFloatingTieredWithMinimumPrice
       | Shared.NewFloatingGroupedTieredPrice
+      | PriceEvaluation.NewFloatingGroupedTieredMatrixPrice
       | Shared.NewFloatingTieredPackageWithMinimumPrice
       | Shared.NewFloatingPackageWithAllocationPrice
       | Shared.NewFloatingUnitWithPercentPrice
@@ -4953,6 +5096,147 @@ export namespace PriceEvaluateMultipleParams {
       }
     }
 
+    export interface NewFloatingGroupedTieredMatrixPrice {
+      /**
+       * The cadence to bill for this price on.
+       */
+      cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time' | 'custom';
+
+      /**
+       * An ISO 4217 currency string for which this price is billed in.
+       */
+      currency: string;
+
+      /**
+       * Configuration for grouped_tiered_matrix pricing
+       */
+      grouped_tiered_matrix_config: NewFloatingGroupedTieredMatrixPrice.GroupedTieredMatrixConfig;
+
+      /**
+       * The id of the item the price will be associated with.
+       */
+      item_id: string;
+
+      /**
+       * The pricing model type
+       */
+      model_type: 'grouped_tiered_matrix';
+
+      /**
+       * The name of the price.
+       */
+      name: string;
+
+      /**
+       * The id of the billable metric for the price. Only needed if the price is
+       * usage-based.
+       */
+      billable_metric_id?: string | null;
+
+      /**
+       * If the Price represents a fixed cost, the price will be billed in-advance if
+       * this is true, and in-arrears if this is false.
+       */
+      billed_in_advance?: boolean | null;
+
+      /**
+       * For custom cadence: specifies the duration of the billing period in days or
+       * months.
+       */
+      billing_cycle_configuration?: Shared.NewBillingCycleConfiguration | null;
+
+      /**
+       * The per unit conversion rate of the price currency to the invoicing currency.
+       */
+      conversion_rate?: number | null;
+
+      /**
+       * The configuration for the rate of the price currency to the invoicing currency.
+       */
+      conversion_rate_config?: Shared.UnitConversionRateConfig | Shared.TieredConversionRateConfig | null;
+
+      /**
+       * For dimensional price: specifies a price group and dimension values
+       */
+      dimensional_price_configuration?: Shared.NewDimensionalPriceConfiguration | null;
+
+      /**
+       * An alias for the price.
+       */
+      external_price_id?: string | null;
+
+      /**
+       * If the Price represents a fixed cost, this represents the quantity of units
+       * applied.
+       */
+      fixed_price_quantity?: number | null;
+
+      /**
+       * The property used to group this price on an invoice
+       */
+      invoice_grouping_key?: string | null;
+
+      /**
+       * Within each billing cycle, specifies the cadence at which invoices are produced.
+       * If unspecified, a single invoice is produced per billing cycle.
+       */
+      invoicing_cycle_configuration?: Shared.NewBillingCycleConfiguration | null;
+
+      /**
+       * The ID of the license type to associate with this price.
+       */
+      license_type_id?: string | null;
+
+      /**
+       * User-specified key/value pairs for the resource. Individual keys can be removed
+       * by setting the value to `null`, and the entire metadata mapping can be cleared
+       * by setting `metadata` to `null`.
+       */
+      metadata?: { [key: string]: string | null } | null;
+    }
+
+    export namespace NewFloatingGroupedTieredMatrixPrice {
+      /**
+       * Configuration for grouped_tiered_matrix pricing
+       */
+      export interface GroupedTieredMatrixConfig {
+        /**
+         * Per unit rate for usage whose dimension value has no configured tiers
+         */
+        default_unit_amount: string;
+
+        /**
+         * The billable metric property used to group usage before tiering
+         */
+        dimension: string;
+
+        /**
+         * Graduated tiers keyed by dimension value; usage for a value is tiered only
+         * against its own rows
+         */
+        tiers: Array<GroupedTieredMatrixConfig.Tier>;
+      }
+
+      export namespace GroupedTieredMatrixConfig {
+        /**
+         * Configuration for a single tier scoped to a dimension value
+         */
+        export interface Tier {
+          /**
+           * The dimension value this tier applies to
+           */
+          dimension_value: string;
+
+          tier_lower_bound: string;
+
+          /**
+           * Per unit amount
+           */
+          unit_amount: string;
+        }
+      }
+    }
+
     export interface NewFloatingMatrixWithThresholdDiscountsPrice {
       /**
        * The cadence to bill for this price on.
@@ -6018,6 +6302,7 @@ export namespace PriceEvaluatePreviewEventsParams {
       | Shared.NewFloatingTieredPackagePrice
       | Shared.NewFloatingTieredWithMinimumPrice
       | Shared.NewFloatingGroupedTieredPrice
+      | PriceEvaluation.NewFloatingGroupedTieredMatrixPrice
       | Shared.NewFloatingTieredPackageWithMinimumPrice
       | Shared.NewFloatingPackageWithAllocationPrice
       | Shared.NewFloatingUnitWithPercentPrice
@@ -6199,6 +6484,147 @@ export namespace PriceEvaluatePreviewEventsParams {
       }
     }
 
+    export interface NewFloatingGroupedTieredMatrixPrice {
+      /**
+       * The cadence to bill for this price on.
+       */
+      cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time' | 'custom';
+
+      /**
+       * An ISO 4217 currency string for which this price is billed in.
+       */
+      currency: string;
+
+      /**
+       * Configuration for grouped_tiered_matrix pricing
+       */
+      grouped_tiered_matrix_config: NewFloatingGroupedTieredMatrixPrice.GroupedTieredMatrixConfig;
+
+      /**
+       * The id of the item the price will be associated with.
+       */
+      item_id: string;
+
+      /**
+       * The pricing model type
+       */
+      model_type: 'grouped_tiered_matrix';
+
+      /**
+       * The name of the price.
+       */
+      name: string;
+
+      /**
+       * The id of the billable metric for the price. Only needed if the price is
+       * usage-based.
+       */
+      billable_metric_id?: string | null;
+
+      /**
+       * If the Price represents a fixed cost, the price will be billed in-advance if
+       * this is true, and in-arrears if this is false.
+       */
+      billed_in_advance?: boolean | null;
+
+      /**
+       * For custom cadence: specifies the duration of the billing period in days or
+       * months.
+       */
+      billing_cycle_configuration?: Shared.NewBillingCycleConfiguration | null;
+
+      /**
+       * The per unit conversion rate of the price currency to the invoicing currency.
+       */
+      conversion_rate?: number | null;
+
+      /**
+       * The configuration for the rate of the price currency to the invoicing currency.
+       */
+      conversion_rate_config?: Shared.UnitConversionRateConfig | Shared.TieredConversionRateConfig | null;
+
+      /**
+       * For dimensional price: specifies a price group and dimension values
+       */
+      dimensional_price_configuration?: Shared.NewDimensionalPriceConfiguration | null;
+
+      /**
+       * An alias for the price.
+       */
+      external_price_id?: string | null;
+
+      /**
+       * If the Price represents a fixed cost, this represents the quantity of units
+       * applied.
+       */
+      fixed_price_quantity?: number | null;
+
+      /**
+       * The property used to group this price on an invoice
+       */
+      invoice_grouping_key?: string | null;
+
+      /**
+       * Within each billing cycle, specifies the cadence at which invoices are produced.
+       * If unspecified, a single invoice is produced per billing cycle.
+       */
+      invoicing_cycle_configuration?: Shared.NewBillingCycleConfiguration | null;
+
+      /**
+       * The ID of the license type to associate with this price.
+       */
+      license_type_id?: string | null;
+
+      /**
+       * User-specified key/value pairs for the resource. Individual keys can be removed
+       * by setting the value to `null`, and the entire metadata mapping can be cleared
+       * by setting `metadata` to `null`.
+       */
+      metadata?: { [key: string]: string | null } | null;
+    }
+
+    export namespace NewFloatingGroupedTieredMatrixPrice {
+      /**
+       * Configuration for grouped_tiered_matrix pricing
+       */
+      export interface GroupedTieredMatrixConfig {
+        /**
+         * Per unit rate for usage whose dimension value has no configured tiers
+         */
+        default_unit_amount: string;
+
+        /**
+         * The billable metric property used to group usage before tiering
+         */
+        dimension: string;
+
+        /**
+         * Graduated tiers keyed by dimension value; usage for a value is tiered only
+         * against its own rows
+         */
+        tiers: Array<GroupedTieredMatrixConfig.Tier>;
+      }
+
+      export namespace GroupedTieredMatrixConfig {
+        /**
+         * Configuration for a single tier scoped to a dimension value
+         */
+        export interface Tier {
+          /**
+           * The dimension value this tier applies to
+           */
+          dimension_value: string;
+
+          tier_lower_bound: string;
+
+          /**
+           * Per unit amount
+           */
+          unit_amount: string;
+        }
+      }
+    }
+
     export interface NewFloatingMatrixWithThresholdDiscountsPrice {
       /**
        * The cadence to bill for this price on.