orb-billing 2.1.2 → 2.3.0

package/resources/prices/prices.d.ts

@@ -25,6 +25,30 @@ export declare class Prices extends APIResource {
      */
     list(query?: PriceListParams, options?: Core.RequestOptions): Core.PagePromise<PricesPage, Price>;
     list(options?: Core.RequestOptions): Core.PagePromise<PricesPage, Price>;
+    /**
+     * This endpoint is used to evaluate the output of a price for a given customer and
+     * time range. It enables filtering and grouping the output using
+     * [computed properties](../guides/extensibility/advanced-metrics#computed-properties),
+     * supporting the following workflows:
+     *
+     * 1. Showing detailed usage and costs to the end customer.
+     * 2. Auditing subtotals on invoice line items.
+     *
+     * For these workflows, the expressiveness of computed properties in both the
+     * filters and grouping is critical. For example, if you'd like to show your
+     * customer their usage grouped by hour and another property, you can do so with
+     * the following `grouping_keys`:
+     * `["hour_floor_timestamp_millis(timestamp_millis)", "my_property"]`. If you'd
+     * like to examine a customer's usage for a specific property value, you can do so
+     * with the following `filter`:
+     * `my_property = 'foo' AND my_other_property = 'bar'`.
+     *
+     * By default, the start of the time range must be no more than 100 days ago and
+     * the length of the results must be no greater than 1000. Note that this is a POST
+     * endpoint rather than a GET endpoint because it employs a JSON body rather than
+     * query parameters.
+     */
+    evaluate(priceId: string, body: PriceEvaluateParams, options?: Core.RequestOptions): Core.APIPromise<PriceEvaluateResponse>;
     /**
      * This endpoint returns a price given an identifier.
      */
@@ -32,6 +56,20 @@ export declare class Prices extends APIResource {
 }
 export declare class PricesPage extends Page<Price> {
 }
+export interface EvaluatePriceGroup {
+    /**
+     * The price's output for the group
+     */
+    amount: string;
+    /**
+     * The values for the group in the order specified by `grouping_keys`
+     */
+    grouping_values: Array<string | number | boolean>;
+    /**
+     * The price's usage quantity for the group
+     */
+    quantity: number;
+}
 /**
  * The Price resource represents a price that can be billed on a subscription,
  * resulting in a charge on an invoice in the form of an invoice line item. Prices
@@ -265,13 +303,14 @@ export declare class PricesPage extends Page<Price> {
  * }
  * ```
  */
-export type Price = Price.UnitPrice | Price.PackagePrice | Price.MatrixPrice | Price.TieredPrice | Price.TieredBpsPrice | Price.BpsPrice | Price.BulkBpsPrice | Price.BulkPrice | Price.ThresholdTotalAmountPrice | Price.TieredPackagePrice | Price.TieredWithMinimumPrice | Price.PackageWithAllocationPrice | Price.UnitWithPercentPrice | Price.MatrixWithAllocationPrice;
+export type Price = Price.UnitPrice | Price.PackagePrice | Price.MatrixPrice | Price.TieredPrice | Price.TieredBpsPrice | Price.BpsPrice | Price.BulkBpsPrice | Price.BulkPrice | Price.ThresholdTotalAmountPrice | Price.TieredPackagePrice | Price.GroupedTieredPrice | Price.TieredWithMinimumPrice | Price.TieredPackageWithMinimumPrice | Price.PackageWithAllocationPrice | Price.UnitWithPercentPrice | Price.MatrixWithAllocationPrice;
 export declare namespace Price {
     interface UnitPrice {
         id: string;
         billable_metric: UnitPrice.BillableMetric | null;
         cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
         created_at: string;
+        credit_allocation: UnitPrice.CreditAllocation | null;
         currency: string;
         discount: Shared.Discount | null;
         external_price_id: string | null;
@@ -291,6 +330,10 @@ export declare namespace Price {
         interface BillableMetric {
             id: string;
         }
+        interface CreditAllocation {
+            allows_rollover: boolean;
+            currency: string;
+        }
         interface Item {
             id: string;
             name: string;
@@ -329,6 +372,7 @@ export declare namespace Price {
         billable_metric: PackagePrice.BillableMetric | null;
         cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
         created_at: string;
+        credit_allocation: PackagePrice.CreditAllocation | null;
         currency: string;
         discount: Shared.Discount | null;
         external_price_id: string | null;
@@ -348,6 +392,10 @@ export declare namespace Price {
         interface BillableMetric {
             id: string;
         }
+        interface CreditAllocation {
+            allows_rollover: boolean;
+            currency: string;
+        }
         interface Item {
             id: string;
             name: string;
@@ -391,6 +439,7 @@ export declare namespace Price {
         billable_metric: MatrixPrice.BillableMetric | null;
         cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
         created_at: string;
+        credit_allocation: MatrixPrice.CreditAllocation | null;
         currency: string;
         discount: Shared.Discount | null;
         external_price_id: string | null;
@@ -410,6 +459,10 @@ export declare namespace Price {
         interface BillableMetric {
             id: string;
         }
+        interface CreditAllocation {
+            allows_rollover: boolean;
+            currency: string;
+        }
         interface Item {
             id: string;
             name: string;
@@ -470,6 +523,7 @@ export declare namespace Price {
         billable_metric: TieredPrice.BillableMetric | null;
         cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
         created_at: string;
+        credit_allocation: TieredPrice.CreditAllocation | null;
         currency: string;
         discount: Shared.Discount | null;
         external_price_id: string | null;
@@ -489,6 +543,10 @@ export declare namespace Price {
         interface BillableMetric {
             id: string;
         }
+        interface CreditAllocation {
+            allows_rollover: boolean;
+            currency: string;
+        }
         interface Item {
             id: string;
             name: string;
@@ -543,6 +601,7 @@ export declare namespace Price {
         billable_metric: TieredBpsPrice.BillableMetric | null;
         cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
         created_at: string;
+        credit_allocation: TieredBpsPrice.CreditAllocation | null;
         currency: string;
         discount: Shared.Discount | null;
         external_price_id: string | null;
@@ -562,6 +621,10 @@ export declare namespace Price {
         interface BillableMetric {
             id: string;
         }
+        interface CreditAllocation {
+            allows_rollover: boolean;
+            currency: string;
+        }
         interface Item {
             id: string;
             name: string;
@@ -622,6 +685,7 @@ export declare namespace Price {
         bps_config: BpsPrice.BpsConfig;
         cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
         created_at: string;
+        credit_allocation: BpsPrice.CreditAllocation | null;
         currency: string;
         discount: Shared.Discount | null;
         external_price_id: string | null;
@@ -650,6 +714,10 @@ export declare namespace Price {
              */
             per_unit_maximum?: string | null;
         }
+        interface CreditAllocation {
+            allows_rollover: boolean;
+            currency: string;
+        }
         interface Item {
             id: string;
             name: string;
@@ -683,6 +751,7 @@ export declare namespace Price {
         bulk_bps_config: BulkBpsPrice.BulkBpsConfig;
         cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
         created_at: string;
+        credit_allocation: BulkBpsPrice.CreditAllocation | null;
         currency: string;
         discount: Shared.Discount | null;
         external_price_id: string | null;
@@ -724,6 +793,10 @@ export declare namespace Price {
                 per_unit_maximum?: string | null;
             }
         }
+        interface CreditAllocation {
+            allows_rollover: boolean;
+            currency: string;
+        }
         interface Item {
             id: string;
             name: string;
@@ -757,6 +830,7 @@ export declare namespace Price {
         bulk_config: BulkPrice.BulkConfig;
         cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
         created_at: string;
+        credit_allocation: BulkPrice.CreditAllocation | null;
         currency: string;
         discount: Shared.Discount | null;
         external_price_id: string | null;
@@ -793,6 +867,10 @@ export declare namespace Price {
                 maximum_units?: number | null;
             }
         }
+        interface CreditAllocation {
+            allows_rollover: boolean;
+            currency: string;
+        }
         interface Item {
             id: string;
             name: string;
@@ -825,6 +903,7 @@ export declare namespace Price {
         billable_metric: ThresholdTotalAmountPrice.BillableMetric | null;
         cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
         created_at: string;
+        credit_allocation: ThresholdTotalAmountPrice.CreditAllocation | null;
         currency: string;
         discount: Shared.Discount | null;
         external_price_id: string | null;
@@ -844,6 +923,10 @@ export declare namespace Price {
         interface BillableMetric {
             id: string;
         }
+        interface CreditAllocation {
+            allows_rollover: boolean;
+            currency: string;
+        }
         interface Item {
             id: string;
             name: string;
@@ -876,6 +959,7 @@ export declare namespace Price {
         billable_metric: TieredPackagePrice.BillableMetric | null;
         cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
         created_at: string;
+        credit_allocation: TieredPackagePrice.CreditAllocation | null;
         currency: string;
         discount: Shared.Discount | null;
         external_price_id: string | null;
@@ -895,6 +979,66 @@ export declare namespace Price {
         interface BillableMetric {
             id: string;
         }
+        interface CreditAllocation {
+            allows_rollover: boolean;
+            currency: string;
+        }
+        interface Item {
+            id: string;
+            name: string;
+        }
+        interface Maximum {
+            /**
+             * List of price_ids that this maximum amount applies to. For plan/plan phase
+             * maximums, this can be a subset of prices.
+             */
+            applies_to_price_ids: Array<string>;
+            /**
+             * Maximum amount applied
+             */
+            maximum_amount: string;
+        }
+        interface Minimum {
+            /**
+             * List of price_ids that this minimum amount applies to. For plan/plan phase
+             * minimums, this can be a subset of prices.
+             */
+            applies_to_price_ids: Array<string>;
+            /**
+             * Minimum amount applied
+             */
+            minimum_amount: string;
+        }
+    }
+    interface GroupedTieredPrice {
+        id: string;
+        billable_metric: GroupedTieredPrice.BillableMetric | null;
+        cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
+        created_at: string;
+        credit_allocation: GroupedTieredPrice.CreditAllocation | null;
+        currency: string;
+        discount: Shared.Discount | null;
+        external_price_id: string | null;
+        fixed_price_quantity: number | null;
+        grouped_tiered_config: Record<string, unknown>;
+        item: GroupedTieredPrice.Item;
+        maximum: GroupedTieredPrice.Maximum | null;
+        maximum_amount: string | null;
+        minimum: GroupedTieredPrice.Minimum | null;
+        minimum_amount: string | null;
+        model_type: 'grouped_tiered';
+        name: string;
+        plan_phase_order: number | null;
+        price_type: 'usage_price' | 'fixed_price';
+    }
+    namespace GroupedTieredPrice {
+        interface BillableMetric {
+            id: string;
+        }
+        interface CreditAllocation {
+            allows_rollover: boolean;
+            currency: string;
+        }
         interface Item {
             id: string;
             name: string;
@@ -927,6 +1071,7 @@ export declare namespace Price {
         billable_metric: TieredWithMinimumPrice.BillableMetric | null;
         cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
         created_at: string;
+        credit_allocation: TieredWithMinimumPrice.CreditAllocation | null;
         currency: string;
         discount: Shared.Discount | null;
         external_price_id: string | null;
@@ -946,6 +1091,66 @@ export declare namespace Price {
         interface BillableMetric {
             id: string;
         }
+        interface CreditAllocation {
+            allows_rollover: boolean;
+            currency: string;
+        }
+        interface Item {
+            id: string;
+            name: string;
+        }
+        interface Maximum {
+            /**
+             * List of price_ids that this maximum amount applies to. For plan/plan phase
+             * maximums, this can be a subset of prices.
+             */
+            applies_to_price_ids: Array<string>;
+            /**
+             * Maximum amount applied
+             */
+            maximum_amount: string;
+        }
+        interface Minimum {
+            /**
+             * List of price_ids that this minimum amount applies to. For plan/plan phase
+             * minimums, this can be a subset of prices.
+             */
+            applies_to_price_ids: Array<string>;
+            /**
+             * Minimum amount applied
+             */
+            minimum_amount: string;
+        }
+    }
+    interface TieredPackageWithMinimumPrice {
+        id: string;
+        billable_metric: TieredPackageWithMinimumPrice.BillableMetric | null;
+        cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
+        created_at: string;
+        credit_allocation: TieredPackageWithMinimumPrice.CreditAllocation | null;
+        currency: string;
+        discount: Shared.Discount | null;
+        external_price_id: string | null;
+        fixed_price_quantity: number | null;
+        item: TieredPackageWithMinimumPrice.Item;
+        maximum: TieredPackageWithMinimumPrice.Maximum | null;
+        maximum_amount: string | null;
+        minimum: TieredPackageWithMinimumPrice.Minimum | null;
+        minimum_amount: string | null;
+        model_type: 'tiered_package_with_minimum';
+        name: string;
+        plan_phase_order: number | null;
+        price_type: 'usage_price' | 'fixed_price';
+        tiered_package_with_minimum_config: Record<string, unknown>;
+    }
+    namespace TieredPackageWithMinimumPrice {
+        interface BillableMetric {
+            id: string;
+        }
+        interface CreditAllocation {
+            allows_rollover: boolean;
+            currency: string;
+        }
         interface Item {
             id: string;
             name: string;
@@ -978,6 +1183,7 @@ export declare namespace Price {
         billable_metric: PackageWithAllocationPrice.BillableMetric | null;
         cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
         created_at: string;
+        credit_allocation: PackageWithAllocationPrice.CreditAllocation | null;
         currency: string;
         discount: Shared.Discount | null;
         external_price_id: string | null;
@@ -997,6 +1203,10 @@ export declare namespace Price {
         interface BillableMetric {
             id: string;
         }
+        interface CreditAllocation {
+            allows_rollover: boolean;
+            currency: string;
+        }
         interface Item {
             id: string;
             name: string;
@@ -1029,6 +1239,7 @@ export declare namespace Price {
         billable_metric: UnitWithPercentPrice.BillableMetric | null;
         cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
         created_at: string;
+        credit_allocation: UnitWithPercentPrice.CreditAllocation | null;
         currency: string;
         discount: Shared.Discount | null;
         external_price_id: string | null;
@@ -1048,6 +1259,10 @@ export declare namespace Price {
         interface BillableMetric {
             id: string;
         }
+        interface CreditAllocation {
+            allows_rollover: boolean;
+            currency: string;
+        }
         interface Item {
             id: string;
             name: string;
@@ -1080,6 +1295,7 @@ export declare namespace Price {
         billable_metric: MatrixWithAllocationPrice.BillableMetric | null;
         cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
         created_at: string;
+        credit_allocation: MatrixWithAllocationPrice.CreditAllocation | null;
         currency: string;
         discount: Shared.Discount | null;
         external_price_id: string | null;
@@ -1099,6 +1315,10 @@ export declare namespace Price {
         interface BillableMetric {
             id: string;
         }
+        interface CreditAllocation {
+            allows_rollover: boolean;
+            currency: string;
+        }
         interface Item {
             id: string;
             name: string;
@@ -1159,7 +1379,10 @@ export declare namespace Price {
         }
     }
 }
-export type PriceCreateParams = PriceCreateParams.NewFloatingUnitPrice | PriceCreateParams.NewFloatingPackagePrice | PriceCreateParams.NewFloatingMatrixPrice | PriceCreateParams.NewFloatingMatrixWithAllocationPrice | PriceCreateParams.NewFloatingTieredPrice | PriceCreateParams.NewFloatingTieredBpsPrice | PriceCreateParams.NewFloatingBpsPrice | PriceCreateParams.NewFloatingBulkBpsPrice | PriceCreateParams.NewFloatingBulkPrice | PriceCreateParams.NewFloatingThresholdTotalAmountPrice | PriceCreateParams.NewFloatingTieredPackagePrice | PriceCreateParams.NewFloatingTieredWithMinimumPrice | PriceCreateParams.NewFloatingPackageWithAllocationPrice | PriceCreateParams.NewFloatingTieredPackageWithMinimumPrice | PriceCreateParams.NewFloatingUnitWithPercentPrice;
+export interface PriceEvaluateResponse {
+    data: Array<EvaluatePriceGroup>;
+}
+export type PriceCreateParams = PriceCreateParams.NewFloatingUnitPrice | PriceCreateParams.NewFloatingPackagePrice | PriceCreateParams.NewFloatingMatrixPrice | PriceCreateParams.NewFloatingMatrixWithAllocationPrice | PriceCreateParams.NewFloatingTieredPrice | PriceCreateParams.NewFloatingTieredBpsPrice | PriceCreateParams.NewFloatingBpsPrice | PriceCreateParams.NewFloatingBulkBpsPrice | PriceCreateParams.NewFloatingBulkPrice | PriceCreateParams.NewFloatingThresholdTotalAmountPrice | PriceCreateParams.NewFloatingTieredPackagePrice | PriceCreateParams.NewFloatingGroupedTieredPrice | PriceCreateParams.NewFloatingTieredWithMinimumPrice | PriceCreateParams.NewFloatingPackageWithAllocationPrice | PriceCreateParams.NewFloatingTieredPackageWithMinimumPrice | PriceCreateParams.NewFloatingUnitWithPercentPrice;
 export declare namespace PriceCreateParams {
     interface NewFloatingUnitPrice {
         /**
@@ -1829,6 +2052,49 @@ export declare namespace PriceCreateParams {
          */
         invoice_grouping_key?: string | null;
     }
+    interface NewFloatingGroupedTieredPrice {
+        /**
+         * The cadence to bill for this price on.
+         */
+        cadence: 'annual' | 'monthly' | 'quarterly' | 'one_time';
+        /**
+         * An ISO 4217 currency string for which this price is billed in.
+         */
+        currency: string;
+        grouped_tiered_config: Record<string, unknown>;
+        /**
+         * The id of the item the plan will be associated with.
+         */
+        item_id: string;
+        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;
+        /**
+         * 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;
+    }
     interface NewFloatingTieredWithMinimumPrice {
         /**
          * The cadence to bill for this price on.
@@ -2004,11 +2270,44 @@ export declare namespace PriceCreateParams {
 }
 export interface PriceListParams extends PageParams {
 }
+export interface PriceEvaluateParams {
+    /**
+     * The exclusive upper bound for event timestamps
+     */
+    timeframe_end: string;
+    /**
+     * The inclusive lower bound for event timestamps
+     */
+    timeframe_start: string;
+    /**
+     * The ID of the customer to which this evaluation is scoped.
+     */
+    customer_id?: string | null;
+    /**
+     * The external customer ID of the customer to which this evaluation is scoped.
+     */
+    external_customer_id?: string | null;
+    /**
+     * A boolean
+     * [computed property](../guides/extensibility/advanced-metrics#computed-properties)
+     * used to filter the underlying billable metric
+     */
+    filter?: string | null;
+    /**
+     * Properties (or
+     * [computed properties](../guides/extensibility/advanced-metrics#computed-properties))
+     * used to group the underlying billable metric
+     */
+    grouping_keys?: Array<string>;
+}
 export declare namespace Prices {
+    export import EvaluatePriceGroup = PricesAPI.EvaluatePriceGroup;
     export import Price = PricesAPI.Price;
+    export import PriceEvaluateResponse = PricesAPI.PriceEvaluateResponse;
     export import PricesPage = PricesAPI.PricesPage;
     export import PriceCreateParams = PricesAPI.PriceCreateParams;
     export import PriceListParams = PricesAPI.PriceListParams;
+    export import PriceEvaluateParams = PricesAPI.PriceEvaluateParams;
     export import ExternalPriceID = ExternalPriceIDAPI.ExternalPriceID;
 }
 //# sourceMappingURL=prices.d.ts.map