orb-billing
Version:
The official TypeScript library for the Orb API
1,204 lines (1,203 loc) • 75.5 kB
TypeScript
import { APIResource } from "../../core/resource.js";
import * as Shared from "../shared.js";
import * as ExternalPlanIDAPI from "./external-plan-id.js";
import { ExternalPlanID, ExternalPlanIDUpdateParams } from "./external-plan-id.js";
import * as MigrationsAPI from "./migrations.js";
import { MigrationCancelParams, MigrationCancelResponse, MigrationListParams, MigrationListResponse, MigrationListResponsesPage, MigrationRetrieveParams, MigrationRetrieveResponse, Migrations } from "./migrations.js";
import { APIPromise } from "../../core/api-promise.js";
import { Page, type PageParams, PagePromise } from "../../core/pagination.js";
import { RequestOptions } from "../../internal/request-options.js";
/**
* 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 declare class Plans extends APIResource {
externalPlanID: ExternalPlanIDAPI.ExternalPlanID;
migrations: MigrationsAPI.Migrations;
/**
* This endpoint allows creation of plans including their prices.
*/
create(body: PlanCreateParams, options?: RequestOptions): APIPromise<Plan>;
/**
* This endpoint can be used to update the `external_plan_id`, `description`, and
* `metadata` of an existing plan.
*
* Other fields on a plan are currently immutable.
*/
update(planID: string, body: PlanUpdateParams, options?: RequestOptions): APIPromise<Plan>;
/**
* This endpoint returns a list of all [plans](/core-concepts#plan-and-price) for
* an account in a list format. The list of plans is ordered starting from the most
* recently created plan. The response also includes
* [`pagination_metadata`](/api-reference/pagination) which lets the caller
* retrieve the next page of results if they exist.
*/
list(query?: PlanListParams | null | undefined, options?: RequestOptions): PagePromise<PlansPage, Plan>;
/**
* This endpoint is used to fetch [plan](/core-concepts#plan-and-price) details
* given a plan identifier. It returns information about the prices included in the
* plan and their configuration, as well as the product that the plan is attached
* to.
*
* ## Serialized prices
*
* Orb supports a few different pricing models out of the box. Each of these models
* is serialized differently in a given [Price](/core-concepts#plan-and-price)
* object. The `model_type` field determines the key for the configuration object
* that is present. A detailed explanation of price types can be found in the
* [Price schema](/core-concepts#plan-and-price).
*
* ## Phases
*
* Orb supports plan phases, also known as contract ramps. For plans with phases,
* the serialized prices refer to all prices across all phases.
*/
fetch(planID: string, options?: RequestOptions): APIPromise<Plan>;
}
export type PlansPage = Page<Plan>;
/**
* 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 interface Plan {
id: string;
/**
* 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 | Plan.PlanPhaseTieredPercentageDiscountAdjustment | Shared.PlanPhaseMinimumAdjustment | Shared.PlanPhaseMaximumAdjustment>;
/**
* @deprecated Legacy field representing the parent plan if the current plan is a
* 'child plan', overriding prices from the parent.
*/
base_plan: Plan.BasePlan | null;
/**
* @deprecated Legacy field representing the parent plan ID if the current plan is
* a 'child plan', overriding prices from the parent.
*/
base_plan_id: string | null;
created_at: string;
/**
* @deprecated An ISO 4217 currency string or custom pricing unit (`credits`) for
* this plan's prices.
*/
currency: string;
/**
* The default memo text on the invoices corresponding to subscriptions on this
* plan. Note that each subscription may configure its own memo.
*/
default_invoice_memo: string | null;
description: string;
/**
* @deprecated
*/
discount: Shared.Discount | null;
/**
* An optional user-defined ID for this plan resource, used throughout the system
* as an alias for this Plan. Use this field to identify a plan by an existing
* identifier in your system.
*/
external_plan_id: string | null;
/**
* An ISO 4217 currency string for which this plan is billed in. Matches `currency`
* unless `currency` is a custom pricing unit.
*/
invoicing_currency: string;
/**
* @deprecated
*/
maximum: Shared.Maximum | null;
/**
* @deprecated
*/
maximum_amount: string | null;
/**
* User specified key-value pairs for the resource. If not present, this defaults
* to an empty dictionary. 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;
};
/**
* @deprecated
*/
minimum: Shared.Minimum | null;
/**
* @deprecated
*/
minimum_amount: string | null;
name: string;
/**
* Determines the difference between the invoice issue date and the due date. A
* value of "0" here signifies that invoices are due on issue, whereas a value of
* "30" means that the customer has a month to pay the invoice before its overdue.
* Note that individual subscriptions or invoices may set a different net terms
* configuration.
*/
net_terms: number | null;
plan_phases: Array<Plan.PlanPhase> | null;
/**
* Prices for this plan. If the plan has phases, this includes prices across all
* phases of the plan.
*/
prices: Array<Shared.Price>;
product: Plan.Product;
status: 'active' | 'archived' | 'draft';
trial_config: Plan.TrialConfig;
version: number;
}
export declare namespace Plan {
interface PlanPhaseTieredPercentageDiscountAdjustment {
id: string;
adjustment_type: 'tiered_percentage_discount';
/**
* @deprecated The price IDs that this adjustment applies to.
*/
applies_to_price_ids: Array<string>;
/**
* The filters that determine which prices to apply this adjustment to.
*/
filters: Array<PlanPhaseTieredPercentageDiscountAdjustment.Filter>;
/**
* True for adjustments that apply to an entire invoice, false for adjustments that
* apply to only one price.
*/
is_invoice_level: boolean;
/**
* The plan phase in which this adjustment is active.
*/
plan_phase_order: number | null;
/**
* The reason for the adjustment.
*/
reason: string | null;
/**
* The adjustment id this adjustment replaces. This adjustment will take the place
* of the replaced adjustment in plan version migrations.
*/
replaces_adjustment_id: string | null;
/**
* The ordered, contiguous bands of cumulative eligible spend, each discounted at
* its own percentage (progressive fill-a-tier), applied to the prices this
* adjustment covers in a given billing period.
*/
tiers: Array<PlanPhaseTieredPercentageDiscountAdjustment.Tier>;
}
namespace PlanPhaseTieredPercentageDiscountAdjustment {
interface Filter {
/**
* The property of the price to filter on.
*/
field: 'price_id' | 'item_id' | 'price_type' | 'currency' | 'pricing_unit_id';
/**
* Should prices that match the filter be included or excluded.
*/
operator: 'includes' | 'excludes';
/**
* The IDs or values that match this filter.
*/
values: Array<string>;
}
/**
* One band of a tiered percentage discount. Bounds are denominated in the
* discount's currency. `lower_bound` is the exclusive start of the band and
* `upper_bound` is the inclusive end; `upper_bound` is null only for the
* open-ended final tier.
*/
interface Tier {
/**
* Exclusive lower bound of cumulative spend for this tier.
*/
lower_bound: number;
/**
* The percentage (between 0 and 1) discounted from spend that falls within this
* tier.
*/
percentage: number;
/**
* Inclusive upper bound of cumulative spend for this tier; null for the final
* open-ended tier.
*/
upper_bound?: number | null;
}
}
/**
* @deprecated Legacy field representing the parent plan if the current plan is a
* 'child plan', overriding prices from the parent.
*/
interface BasePlan {
id: string | null;
/**
* An optional user-defined ID for this plan resource, used throughout the system
* as an alias for this Plan. Use this field to identify a plan by an existing
* identifier in your system.
*/
external_plan_id: string | null;
name: string | null;
}
interface PlanPhase {
id: string;
description: string | null;
discount: Shared.Discount | 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;
maximum: Shared.Maximum | null;
maximum_amount: string | null;
minimum: Shared.Minimum | null;
minimum_amount: string | null;
name: string;
/**
* Determines the ordering of the phase in a plan's lifecycle. 1 = first phase.
*/
order: number;
}
interface Product {
id: string;
created_at: string;
name: string;
}
interface TrialConfig {
trial_period: number | null;
trial_period_unit: 'days';
}
}
export interface PlanCreateParams {
/**
* An ISO 4217 currency string for invoices generated by subscriptions on this
* plan.
*/
currency: string;
name: string;
/**
* Prices for this plan. If the plan has phases, this includes prices across all
* phases of the plan.
*/
prices: Array<PlanCreateParams.Price>;
/**
* Adjustments for this plan. If the plan has phases, this includes adjustments
* across all phases of the plan.
*/
adjustments?: Array<PlanCreateParams.Adjustment> | null;
/**
* Free-form text which is available on the invoice PDF and the Orb invoice portal.
*/
default_invoice_memo?: string | null;
/**
* An optional user-defined description of the plan.
*/
description?: string | null;
external_plan_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;
/**
* The net terms determines the difference between the invoice date and the issue
* date for the invoice. If you intend the invoice to be due on issue, set this
* to 0.
*/
net_terms?: number | null;
/**
* Configuration of pre-defined phases, each with their own prices and adjustments.
* Leave unspecified for plans with a single phase.
*/
plan_phases?: Array<PlanCreateParams.PlanPhase> | null;
/**
* The status of the plan to create (either active or draft). If not specified,
* this defaults to active.
*/
status?: 'active' | 'draft';
}
export declare namespace PlanCreateParams {
interface Price {
/**
* 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?: Price.LicenseAllocationPrice | 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 | Price.NewPlanBulkWithFiltersPrice | Shared.NewPlanPackagePrice | Shared.NewPlanMatrixPrice | Shared.NewPlanThresholdTotalAmountPrice | Shared.NewPlanTieredPackagePrice | Shared.NewPlanTieredWithMinimumPrice | Shared.NewPlanGroupedTieredPrice | Price.NewPlanGroupedTieredMatrixPrice | Shared.NewPlanTieredPackageWithMinimumPrice | Shared.NewPlanPackageWithAllocationPrice | Shared.NewPlanUnitWithPercentPrice | Shared.NewPlanMatrixWithAllocationPrice | Price.NewPlanMatrixWithThresholdDiscountsPrice | Price.NewPlanTieredWithProrationPrice | Shared.NewPlanUnitWithProrationPrice | Shared.NewPlanGroupedAllocationPrice | Shared.NewPlanBulkWithProrationPrice | Shared.NewPlanGroupedWithProratedMinimumPrice | Shared.NewPlanGroupedWithMeteredMinimumPrice | Price.NewPlanGroupedWithMinMaxThresholdsPrice | Shared.NewPlanMatrixWithDisplayNamePrice | Shared.NewPlanGroupedTieredPackagePrice | Shared.NewPlanMaxGroupTieredPackagePrice | Shared.NewPlanScalableMatrixWithUnitPricingPrice | Shared.NewPlanScalableMatrixWithTieredPricingPrice | Shared.NewPlanCumulativeGroupedBulkPrice | Price.NewPlanCumulativeGroupedAllocationPrice | Price.NewPlanDailyCreditAllowancePrice | Price.NewPlanMeteredAllowancePrice | Shared.NewPlanMinimumCompositePrice | Price.NewPlanPercentCompositePrice | Price.NewPlanEventOutputPrice | null;
}
namespace Price {
/**
* The license allocation price to add to the plan.
*/
interface LicenseAllocationPrice {
/**
* 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<LicenseAllocationPrice.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;
}
namespace LicenseAllocationPrice {
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;
}
}
interface NewPlanBulkWithFiltersPrice {
/**
* Configuration for bulk_with_filters pricing
*/
bulk_with_filters_config: NewPlanBulkWithFiltersPrice.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;
/**
* 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;
}
namespace NewPlanBulkWithFiltersPrice {
/**
* Configuration for bulk_with_filters pricing
*/
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>;
}
namespace BulkWithFiltersConfig {
/**
* Configuration for a single property filter
*/
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
*/
interface Tier {
/**
* Amount per unit
*/
unit_amount: string;
/**
* The lower bound for this tier
*/
tier_lower_bound?: string | null;
}
}
}
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;
}
namespace NewPlanGroupedTieredMatrixPrice {
/**
* Configuration for grouped_tiered_matrix pricing
*/
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>;
}
namespace GroupedTieredMatrixConfig {
/**
* Configuration for a single tier scoped to a dimension value
*/
interface Tier {
/**
* The dimension value this tier applies to
*/
dimension_value: string;
tier_lower_bound: string;
/**
* Per unit amount
*/
unit_amount: string;
}
}
}
interface NewPlanMatrixWithThresholdDiscountsPrice {
/**
* 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;
/**
* Configuration for matrix_with_threshold_discounts pricing
*/
matrix_with_threshold_discounts_config: NewPlanMatrixWithThresholdDiscountsPrice.MatrixWithThresholdDiscountsConfig;
/**
* The pricing model type
*/
model_type: 'matrix_with_threshold_discounts';
/**
* 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;
}
namespace NewPlanMatrixWithThresholdDiscountsPrice {
/**
* Configuration for matrix_with_threshold_discounts pricing
*/
interface MatrixWithThresholdDiscountsConfig {
/**
* Unit price used for usage that does not match any defined matrix cell.
*/
default_unit_amount: string;
/**
* First matrix dimension key.
*/
first_dimension: string;
/**
* Per-cell unit prices.
*/
matrix_values: Array<MatrixWithThresholdDiscountsConfig.MatrixValue>;
/**
* Optional second matrix dimension key.
*/
second_dimension?: string | null;
threshold_discount_groups?: Array<MatrixWithThresholdDiscountsConfig.ThresholdDiscountGroup>;
}
namespace MatrixWithThresholdDiscountsConfig {
interface MatrixValue {
first_dimension_value: string;
unit_amount: string;
second_dimension_value?: string | null;
}
interface ThresholdDiscountGroup {
/**
* Discount rate applied to spend above the threshold.
*/
above_threshold_discount_percentage: string;
/**
* Discount rate applied to spend at or below the threshold. Set to 0 for no
* baseline discount.
*/
below_threshold_discount_percentage: string;
/**
* Semicolon-separated list of matrix cell coordinates targeted by this group. Each
* coordinate is `first,second` when the matrix has two dimensions, or just `first`
* for a single-dimension matrix. Example: `blue,circle;green,triangle`.
*/
cell_coordinates: string;
threshold_amount: string;
description?: string | null;
}
}
}
interface NewPlanTieredWithProrationPrice {
/**
* 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;
/**
* The pricing model type
*/
model_type: 'tiered_with_proration';
/**
* The name of the price.
*/
name: string;
/**
* Configuration for tiered_with_proration pricing
*/
tiered_with_proration_config: NewPlanTieredWithProrationPrice.TieredWithProrationConfig;
/**
* 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;
}
namespace NewPlanTieredWithProrationPrice {
/**
* Configuration for tiered_with_proration pricing
*/
interface TieredWithProrationConfig {
/**
* Tiers for rating based on total usage quantities into the specified tier with
* proration
*/
tiers: Array<TieredWithProrationConfig.Tier>;
}
namespace TieredWithProrationConfig {
/**
* Configuration for a single tiered with proration tier
*/
interface Tier {
/**
* Inclusive tier starting value
*/
tier_lower_bound: string;
/**
* Amount per unit
*/
unit_amount: string;
}
}
}
interface NewPlanGroupedWithMinMaxThresholdsPrice {
/**
* The cadence to bill for this price on.
*/
cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time' | 'custom';
/**
* Configuration for grouped_with_min_max_thresholds pricing
*/
grouped_with_min_max_thresholds_config: NewPlanGroupedWithMinMaxThresholdsPrice.GroupedWithMinMaxThresholdsConfig;
/**
* The id of the item the price will be associated with.
*/
item_id: string;
/**
* The pricing model type
*/
model_type: 'grouped_with_min_max_thresholds';
/**
* 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;
}
namespace NewPlanGroupedWithMinMaxThresholdsPrice {
/**
* Configuration for grouped_with_min_max_thresholds pricing
*/
interface GroupedWithMinMaxThresholdsConfig {
/**
* The event property used to group before applying thresholds
*/
grouping_key: string;
/**
* The maximum amount to charge each group
*/
maximum_charge: string;
/**
* The minimum amount to charge each group, regardless of usage
*/
minimum_charge: string;
/**
* The base price charged per group
*/
per_unit_rate: string;
}
}
interface NewPlanCumulativeGroupedAllocationPrice {
/**
* The cadence to bill for this price on.
*/
cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time' | 'custom';
/**
* Configuration for cumulative_grouped_allocation pricing
*/
cumulative_grouped_allocation_config: NewPlanCumulativeGroupedAllocationPrice.CumulativeGroupedAllocationConfig;
/**
* The id of the item the price will be associated with.
*/
item_id: string;
/**
* The pricing model type
*/
model_type: 'cumulative_grouped_allocation';
/**
* 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;
}
namespace NewPlanCumulativeGroupedAllocationPrice {
/**
* Configuration for cumulative_grouped_allocation pricing
*/
interface CumulativeGroupedAllocationConfig {
/**
* The overall allocation across all groups
*/
cumulative_allocation: string;
/**
* The allocation per individual group
*/
group_allocation: string;
/**
* The event property used to group usage before applying allocations
*/
grouping_key: string;
/**
* The amount to charge for each unit outside of the allocation
*/
unit_amount: string;
}
}
interface NewPlanDailyCreditAllowancePrice {
/**
* The cadence to bill for this price on.
*/
cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time' | 'custom';
/**
* Configuration for daily_credit_allowance pricing
*/
daily_credit_allowance_config: NewPlanDailyCreditAllowancePrice.DailyCreditAllowanceConfig;
/**