orb-billing/src/resources/beta/beta.ts

The official TypeScript library for the Orb API

// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

import { APIResource } from '../../resource';
import * as Core from '../../core';
import * as Shared from '../shared';
import * as ExternalPlanIDAPI from './external-plan-id';
import {
  ExternalPlanID,
  ExternalPlanIDCreatePlanVersionParams,
  ExternalPlanIDSetDefaultPlanVersionParams,
} from './external-plan-id';
import * as PlansAPI from '../plans/plans';

/**
 * The [Plan](/core-concepts#plan-and-price) resource represents a plan that can be subscribed to by a
 * customer. Plans define the billing behavior of the subscription. You can see more about how to configure prices
 * in the [Price resource](/reference/price).
 */
export class Beta extends APIResource {
  externalPlanId: ExternalPlanIDAPI.ExternalPlanID = new ExternalPlanIDAPI.ExternalPlanID(this._client);

  /**
   * This endpoint allows the creation of a new plan version for an existing plan.
   */
  createPlanVersion(
    planId: string,
    body: BetaCreatePlanVersionParams,
    options?: Core.RequestOptions,
  ): Core.APIPromise<PlanVersion> {
    return this._client.post(`/plans/${planId}/versions`, { body, ...options });
  }

  /**
   * This endpoint is used to fetch a plan version. It returns the phases, prices,
   * and adjustments present on this version of the plan.
   */
  fetchPlanVersion(
    planId: string,
    version: string,
    options?: Core.RequestOptions,
  ): Core.APIPromise<PlanVersion> {
    return this._client.get(`/plans/${planId}/versions/${version}`, options);
  }

  /**
   * This endpoint allows setting the default version of a plan.
   */
  setDefaultPlanVersion(
    planId: string,
    body: BetaSetDefaultPlanVersionParams,
    options?: Core.RequestOptions,
  ): Core.APIPromise<PlansAPI.Plan> {
    return this._client.post(`/plans/${planId}/set_default_version`, { body, ...options });
  }
}

/**
 * The PlanVersion resource represents the prices and adjustments present on a
 * specific version of a plan.
 */
export interface PlanVersion {
  /**
   * Adjustments for this plan. If the plan has phases, this includes adjustments
   * across all phases of the plan.
   */
  adjustments: Array<
    | Shared.PlanPhaseUsageDiscountAdjustment
    | Shared.PlanPhaseAmountDiscountAdjustment
    | Shared.PlanPhasePercentageDiscountAdjustment
    | Shared.PlanPhaseMinimumAdjustment
    | Shared.PlanPhaseMaximumAdjustment
  >;

  created_at: string;

  plan_phases: Array<PlanVersionPhase> | null;

  /**
   * Prices for this plan. If the plan has phases, this includes prices across all
   * phases of the plan.
   */
  prices: Array<Shared.Price>;

  version: number;
}

export interface PlanVersionPhase {
  id: string;

  description: string | null;

  /**
   * How many terms of length `duration_unit` this phase is active for. If null, this
   * phase is evergreen and active indefinitely
   */
  duration: number | null;

  duration_unit: 'daily' | 'monthly' | 'quarterly' | 'semi_annual' | 'annual' | null;

  name: string;

  /**
   * Determines the ordering of the phase in a plan's lifecycle. 1 = first phase.
   */
  order: number;
}

export interface BetaCreatePlanVersionParams {
  /**
   * New version number.
   */
  version: number;

  /**
   * Additional adjustments to be added to the plan.
   */
  add_adjustments?: Array<BetaCreatePlanVersionParams.AddAdjustment> | null;

  /**
   * Additional prices to be added to the plan.
   */
  add_prices?: Array<BetaCreatePlanVersionParams.AddPrice> | null;

  /**
   * Adjustments to be removed from the plan.
   */
  remove_adjustments?: Array<BetaCreatePlanVersionParams.RemoveAdjustment> | null;

  /**
   * Prices to be removed from the plan.
   */
  remove_prices?: Array<BetaCreatePlanVersionParams.RemovePrice> | null;

  /**
   * Adjustments to be replaced with additional adjustments on the plan.
   */
  replace_adjustments?: Array<BetaCreatePlanVersionParams.ReplaceAdjustment> | null;

  /**
   * Prices to be replaced with additional prices on the plan.
   */
  replace_prices?: Array<BetaCreatePlanVersionParams.ReplacePrice> | null;

  /**
   * Set this new plan version as the default
   */
  set_as_default?: boolean | null;
}

export namespace BetaCreatePlanVersionParams {
  export interface AddAdjustment {
    /**
     * The definition of a new adjustment to create and add to the plan.
     */
    adjustment:
      | Shared.NewPercentageDiscount
      | Shared.NewUsageDiscount
      | Shared.NewAmountDiscount
      | Shared.NewMinimum
      | Shared.NewMaximum;

    /**
     * The phase to add this adjustment to.
     */
    plan_phase_order?: number | null;
  }

  export interface AddPrice {
    /**
     * The allocation price to add to the plan.
     */
    allocation_price?: Shared.NewAllocationPrice | null;

    /**
     * The license allocation price to add to the plan.
     */
    license_allocation_price?:
      | AddPrice.NewLicenseAllocationUnitPrice
      | AddPrice.NewLicenseAllocationTieredPrice
      | AddPrice.NewLicenseAllocationBulkPrice
      | AddPrice.NewLicenseAllocationBulkWithFiltersPrice
      | AddPrice.NewLicenseAllocationPackagePrice
      | AddPrice.NewLicenseAllocationMatrixPrice
      | AddPrice.NewLicenseAllocationThresholdTotalAmountPrice
      | AddPrice.NewLicenseAllocationTieredPackagePrice
      | AddPrice.NewLicenseAllocationTieredWithMinimumPrice
      | AddPrice.NewLicenseAllocationGroupedTieredPrice
      | AddPrice.NewLicenseAllocationTieredPackageWithMinimumPrice
      | AddPrice.NewLicenseAllocationPackageWithAllocationPrice
      | AddPrice.NewLicenseAllocationUnitWithPercentPrice
      | AddPrice.NewLicenseAllocationMatrixWithAllocationPrice
      | AddPrice.NewLicenseAllocationTieredWithProrationPrice
      | AddPrice.NewLicenseAllocationUnitWithProrationPrice
      | AddPrice.NewLicenseAllocationGroupedAllocationPrice
      | AddPrice.NewLicenseAllocationBulkWithProrationPrice
      | AddPrice.NewLicenseAllocationGroupedWithProratedMinimumPrice
      | AddPrice.NewLicenseAllocationGroupedWithMeteredMinimumPrice
      | AddPrice.NewLicenseAllocationGroupedWithMinMaxThresholdsPrice
      | AddPrice.NewLicenseAllocationMatrixWithDisplayNamePrice
      | AddPrice.NewLicenseAllocationGroupedTieredPackagePrice
      | AddPrice.NewLicenseAllocationMaxGroupTieredPackagePrice
      | AddPrice.NewLicenseAllocationScalableMatrixWithUnitPricingPrice
      | AddPrice.NewLicenseAllocationScalableMatrixWithTieredPricingPrice
      | AddPrice.NewLicenseAllocationCumulativeGroupedBulkPrice
      | AddPrice.NewLicenseAllocationCumulativeGroupedAllocationPrice
      | AddPrice.NewLicenseAllocationMinimumCompositePrice
      | AddPrice.NewLicenseAllocationPercentCompositePrice
      | AddPrice.NewLicenseAllocationEventOutputPrice
      | null;

    /**
     * The phase to add this price to.
     */
    plan_phase_order?: number | null;

    /**
     * New plan price request body params.
     */
    price?:
      | Shared.NewPlanUnitPrice
      | Shared.NewPlanTieredPrice
      | Shared.NewPlanBulkPrice
      | AddPrice.NewPlanBulkWithFiltersPrice
      | Shared.NewPlanPackagePrice
      | Shared.NewPlanMatrixPrice
      | Shared.NewPlanThresholdTotalAmountPrice
      | Shared.NewPlanTieredPackagePrice
      | Shared.NewPlanTieredWithMinimumPrice
      | Shared.NewPlanGroupedTieredPrice
      | Shared.NewPlanTieredPackageWithMinimumPrice
      | Shared.NewPlanPackageWithAllocationPrice
      | Shared.NewPlanUnitWithPercentPrice
      | Shared.NewPlanMatrixWithAllocationPrice
      | AddPrice.NewPlanTieredWithProrationPrice
      | Shared.NewPlanUnitWithProrationPrice
      | Shared.NewPlanGroupedAllocationPrice
      | Shared.NewPlanBulkWithProrationPrice
      | Shared.NewPlanGroupedWithProratedMinimumPrice
      | Shared.NewPlanGroupedWithMeteredMinimumPrice
      | AddPrice.NewPlanGroupedWithMinMaxThresholdsPrice
      | Shared.NewPlanMatrixWithDisplayNamePrice
      | Shared.NewPlanGroupedTieredPackagePrice
      | Shared.NewPlanMaxGroupTieredPackagePrice
      | Shared.NewPlanScalableMatrixWithUnitPricingPrice
      | Shared.NewPlanScalableMatrixWithTieredPricingPrice
      | Shared.NewPlanCumulativeGroupedBulkPrice
      | AddPrice.NewPlanCumulativeGroupedAllocationPrice
      | Shared.NewPlanMinimumCompositePrice
      | AddPrice.NewPlanPercentCompositePrice
      | AddPrice.NewPlanEventOutputPrice
      | null;
  }

  export namespace AddPrice {
    export interface NewLicenseAllocationUnitPrice {
      /**
       * The cadence to bill for this price on.
       */
      cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time' | 'custom';

      /**
       * The id of the item the price will be associated with.
       */
      item_id: string;

      /**
       * License allocations to associate with this price. Each entry defines a
       * per-license credit pool granted each cadence. Requires license_type_id or
       * license_type_configuration to be set.
       */
      license_allocations: Array<NewLicenseAllocationUnitPrice.LicenseAllocation>;

      /**
       * The pricing model type
       */
      model_type: 'unit';

      /**
       * The name of the price.
       */
      name: string;

      /**
       * Configuration for unit pricing
       */
      unit_config: Shared.UnitConfig;

      /**
       * 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 NewLicenseAllocationUnitPrice {
      export interface LicenseAllocation {
        /**
         * The amount of credits granted per active license per cadence.
         */
        amount: string;

        /**
         * The currency of the license allocation.
         */
        currency: string;

        /**
         * When True, overage beyond the allocation is written off.
         */
        write_off_overage?: boolean | null;
      }
    }

    export interface NewLicenseAllocationTieredPrice {
      /**
       * The cadence to bill for this price on.
       */
      cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time' | 'custom';

      /**
       * The id of the item the price will be associated with.
       */
      item_id: string;

      /**
       * License allocations to associate with this price. Each entry defines a
       * per-license credit pool granted each cadence. Requires license_type_id or
       * license_type_configuration to be set.
       */
      license_allocations: Array<NewLicenseAllocationTieredPrice.LicenseAllocation>;

      /**
       * The pricing model type
       */
      model_type: 'tiered';

      /**
       * The name of the price.
       */
      name: string;

      /**
       * Configuration for tiered pricing
       */
      tiered_config: Shared.TieredConfig;

      /**
       * 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 NewLicenseAllocationTieredPrice {
      export interface LicenseAllocation {
        /**
         * The amount of credits granted per active license per cadence.
         */
        amount: string;

        /**
         * The currency of the license allocation.
         */
        currency: string;

        /**
         * When True, overage beyond the allocation is written off.
         */
        write_off_overage?: boolean | null;
      }
    }

    export interface NewLicenseAllocationBulkPrice {
      /**
       * Configuration for bulk pricing
       */
      bulk_config: Shared.BulkConfig;

      /**
       * The cadence to bill for this price on.
       */
      cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time' | 'custom';

      /**
       * The id of the item the price will be associated with.
       */
      item_id: string;

      /**
       * License allocations to associate with this price. Each entry defines a
       * per-license credit pool granted each cadence. Requires license_type_id or
       * license_type_configuration to be set.
       */
      license_allocations: Array<NewLicenseAllocationBulkPrice.LicenseAllocation>;

      /**
       * The pricing model type
       */
      model_type: 'bulk';

      /**
       * 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 NewLicenseAllocationBulkPrice {
      export interface LicenseAllocation {
        /**
         * The amount of credits granted per active license per cadence.
         */
        amount: string;

        /**
         * The currency of the license allocation.
         */
        currency: string;

        /**
         * When True, overage beyond the allocation is written off.
         */
        write_off_overage?: boolean | null;
      }
    }

    export interface NewLicenseAllocationBulkWithFiltersPrice {
      /**
       * Configuration for bulk_with_filters pricing
       */
      bulk_with_filters_config: NewLicenseAllocationBulkWithFiltersPrice.BulkWithFiltersConfig;

      /**
       * The cadence to bill for this price on.
       */
      cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time' | 'custom';

      /**
       * The id of the item the price will be associated with.
       */
      item_id: string;

      /**
       * License allocations to associate with this price. Each entry defines a
       * per-license credit pool granted each cadence. Requires license_type_id or
       * license_type_configuration to be set.
       */
      license_allocations: Array<NewLicenseAllocationBulkWithFiltersPrice.LicenseAllocation>;

      /**
       * The pricing model type
       */
      model_type: 'bulk_with_filters';

      /**
       * 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 NewLicenseAllocationBulkWithFiltersPrice {
      /**
       * Configuration for bulk_with_filters pricing
       */
      export interface BulkWithFiltersConfig {
        /**
         * Property filters to apply (all must match)
         */
        filters: Array<BulkWithFiltersConfig.Filter>;

        /**
         * Bulk tiers for rating based on total usage volume
         */
        tiers: Array<BulkWithFiltersConfig.Tier>;
      }

      export namespace BulkWithFiltersConfig {
        /**
         * Configuration for a single property filter
         */
        export interface Filter {
          /**
           * Event property key to filter on
           */
          property_key: string;

          /**
           * Event property value to match
           */
          property_value: string;
        }

        /**
         * Configuration for a single bulk pricing tier
         */
        export interface Tier {
          /**
           * Amount per unit
           */
          unit_amount: string;

          /**
           * The lower bound for this tier
           */
          tier_lower_bound?: string | null;
        }
      }

      export interface LicenseAllocation {
        /**
         * The amount of credits granted per active license per cadence.
         */
        amount: string;

        /**
         * The currency of the license allocation.
         */
        currency: string;

        /**
         * When True, overage beyond the allocation is written off.
         */
        write_off_overage?: boolean | null;
      }
    }

    export interface NewLicenseAllocationPackagePrice {
      /**
       * The cadence to bill for this price on.
       */
      cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time' | 'custom';

      /**
       * The id of the item the price will be associated with.
       */
      item_id: string;

      /**
       * License allocations to associate with this price. Each entry defines a
       * per-license credit pool granted each cadence. Requires license_type_id or
       * license_type_configuration to be set.
       */
      license_allocations: Array<NewLicenseAllocationPackagePrice.LicenseAllocation>;

      /**
       * The pricing model type
       */
      model_type: 'package';

      /**
       * The name of the price.
       */
      name: string;

      /**
       * Configuration for package pricing
       */
      package_config: Shared.PackageConfig;

      /**
       * 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 NewLicenseAllocationPackagePrice {
      export interface LicenseAllocation {
        /**
         * The amount of credits granted per active license per cadence.
         */
        amount: string;

        /**
         * The currency of the license allocation.
         */
        currency: string;

        /**
         * When True, overage beyond the allocation is written off.
         */
        write_off_overage?: boolean | null;
      }
    }

    export interface NewLicenseAllocationMatrixPrice {
      /**
       * The cadence to bill for this price on.
       */
      cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time' | 'custom';

      /**
       * The id of the item the price will be associated with.
       */
      item_id: string;

      /**
       * License allocations to associate with this price. Each entry defines a
       * per-license credit pool granted each cadence. Requires license_type_id or
       * license_type_configuration to be set.
       */
      license_allocations: Array<NewLicenseAllocationMatrixPrice.LicenseAllocation>;

      /**
       * Configuration for matrix pricing
       */
      matrix_config: Shared.MatrixConfig;

      /**
       * The pricing model type
       */
      model_type: '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 NewLicenseAllocationMatrixPrice {
      export interface LicenseAllocation {
        /**
         * The amount of credits granted per active license per cadence.
         */
        amount: string;

        /**
         * The currency of the license allocation.
         */
        currency: string;

        /**
         * When True, overage beyond the allocation is written off.
         */
        write_off_overage?: boolean | null;
      }
    }

    export interface NewLicenseAllocationThresholdTotalAmountPrice {
      /**
       * The cadence to bill for this price on.
       */
      cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time' | 'custom';

      /**
       * The id of the item the price will be associated with.
       */
      item_id: string;

      /**
       * License allocations to associate with this price. Each entry defines a
       * per-license credit pool granted each cadence. Requires license_type_id or
       * license_type_configuration to be set.
       */
      license_allocations: Array<NewLicenseAllocationThresholdTotalAmountPrice.LicenseAllocation>;

      /**
       * The pricing model type
       */
      model_type: 'threshold_total_amount';

      /**
       * The name of the price.
       */
      name: string;

      /**
       * Configuration for threshold_total_amount pricing
       */
      threshold_total_amount_config: NewLicenseAllocationThresholdTotalAmountPrice.ThresholdTotalAmountConfig;

      /**
       * 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 NewLicenseAllocationThresholdTotalAmountPrice {
      export interface LicenseAllocation {
        /**
         * The amount of credits granted per active license per cadence.
         */
        amount: string;

        /**
         * The currency of the license allocation.
         */
        currency: string;

        /**
         * When True, overage beyond the allocation is written off.
         */
        write_off_overage?: boolean | null;
      }

      /**
       * Configuration for threshold_total_amount pricing
       */
      export interface ThresholdTotalAmountConfig {
        /**
         * When the quantity consumed passes a provided threshold, the configured total
         * will be charged
         */
        consumption_table: Array<ThresholdTotalAmountConfig.ConsumptionTable>;

        /**
         * If true, the unit price will be prorated to the billing period
         */
        prorate?: boolean | null;
      }

      export namespace ThresholdTotalAmountConfig {
        /**
         * Configuration for a single threshold
         */
        export interface ConsumptionTable {
          threshold: string;

          /**
           * Total amount for this threshold
           */
          total_amount: string;
        }
      }
    }

    export interface NewLicenseAllocationTieredPackagePrice {
      /**
       * The cadence to bill for this price on.
       */
      cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time' | 'custom';

      /**
       * The id of the item the price will be associated with.
       */
      item_id: string;

      /**
       * License allocations to associate with this price. Each entry defines a
       * per-license credit pool granted each cadence. Requires license_type_id or
       * license_type_configuration to be set.
       */
      license_allocations: Array<NewLicenseAllocationTieredPackagePrice.LicenseAllocation>;

      /**
       * The pricing model type
       */
      model_type: 'tiered_package';

      /**
       * The name of the price.
       */
      name: string;

      /**
       * Configuration for tiered_package pricing
       */
      tiered_package_config: NewLicenseAllocationTieredPackagePrice.TieredPackageConfig;

      /**
       * 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 NewLicenseAllocationTieredPackagePrice {
      export interface LicenseAllocation {
        /**
         * The amount of credits granted per active license per cadence.
         */
        amount: string;

        /**
         * The currency of the license allocation.
         */
        currency: string;

        /**
         * When True, overage beyond the allocation is written off.
         */
        write_off_overage?: boolean | null;
      }

      /**
       * Configuration for tiered_package pricing
       */
      export interface TieredPackageConfig {
        package_size: string;

        /**
         * Apply tiered pricing after rounding up the quantity to the package size. Tiers
         * are defined using exclusive lower bounds. The tier bounds are defined based on
         * the total quantity rather than the number of packages, so they must be multiples
         * of the package size.
         */
        tiers: Array<TieredPackageConfig.Tier>;
      }

      export namespace TieredPackageConfig {
        /**
         * Configuration for a single tier with business logic
         */
        export interface Tier {
          /**
           * Price per package
           */
          per_unit: string;

          tier_lower_bound: string;
        }
      }
    }

    export interface NewLicenseAllocationTieredWithMinimumPrice {
      /**
       * The cadence to bill for this price on.
       */
      cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time' | 'custom';

      /**
       * The id of the item the price will be associated with.
       */
      item_id: string;

      /**
       * License allocations to associate with this price. Each entry defines a
       * per-license credit pool granted each cadence. Requires license_type_id or
       * license_type_configuration to be set.
       */
      license_allocations: Array<NewLicenseAllocationTieredWithMinimumPrice.LicenseAllocation>;

      /**
       * The pricing model type
       */
      model_type: 'tiered_with_minimum';

      /**
       * The name of the price.
       */
      name: string;

      /**
       * Configuration for tiered_with_minimum pricing
       */
      tiered_with_minimum_config: NewLicenseAllocationTieredWithMinimumPrice.TieredWithMinimumConfig;

      /**
       * 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 NewLicenseAllocationTieredWithMinimumPrice {
      export interface LicenseAllocation {
        /**
         * The amount of credits granted per active license per cadence.
         */
        amount: string;

        /**
         * The currency of the license allocation.
         */
        currency: string;

        /**
         * When True, overage beyond the allocation is written off.
         */
        write_off_overage?: boolean | null;
      }

      /**
       * Configuration for tiered_with_minimum pricing
       */
      export interface TieredWithMinimumConfig {
        /**
         * Tiered pricing with a minimum amount dependent on the volume tier. Tiers are
         * defined using exclusive lower bounds.
         */
        tiers: Array<TieredWithMinimumConfig.Tier>;

        /**
         * If true, tiers with an accrued amount of 0 will not be included in the rating.
         */
        hide_zero_amount_tiers?: boolean;

        /**
         * If true, the unit price will be prorated to the billing period
         */
        prorate?: boolean;
      }

      export namespace TieredWithMinimumConfig {
        /**
         * Configuration for a single tier
         */
        export interface Tier {
          minimum_amount: string;

          tier_lower_bound: string;

          /**
           * Per unit amount
           */
          unit_amount: string;
        }
      }
    }

    export interface NewLicenseAllocationGroupedTieredPrice {
      /**
       * The cadence to bill for this price on.
       */
      cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time' | 'custom';

      /**
       * Configuration for grouped_tiered pricing
       */
      grouped_tiered_config: NewLicenseAllocationGroupedTieredPrice.GroupedTieredConfig;

      /**
       * The id of the item the price will be associated with.
       */
      item_id: string;

      /**
       * License allocations to associate with this price. Each entry defines a
       * per-license credit pool granted each cadence. Requires license_type_id or
       * license_type_configuration to be set.
       */
      license_allocations: Array<NewLicenseAllocationGroupedTieredPrice.LicenseAllocation>;

      /**
       * The pricing model type
       */
      model_type: 'grouped_tiered';

      /**
       * 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;

      /**