orb-billing 2.2.0 → 2.4.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
@@ -271,7 +309,9 @@ export declare namespace Price {
         id: string;
         billable_metric: UnitPrice.BillableMetric | null;
         cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
+        conversion_rate: number | null;
         created_at: string;
+        credit_allocation: UnitPrice.CreditAllocation | null;
         currency: string;
         discount: Shared.Discount | null;
         external_price_id: string | null;
@@ -291,6 +331,10 @@ export declare namespace Price {
         interface BillableMetric {
             id: string;
         }
+        interface CreditAllocation {
+            allows_rollover: boolean;
+            currency: string;
+        }
         interface Item {
             id: string;
             name: string;
@@ -328,7 +372,9 @@ export declare namespace Price {
         id: string;
         billable_metric: PackagePrice.BillableMetric | null;
         cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
+        conversion_rate: number | null;
         created_at: string;
+        credit_allocation: PackagePrice.CreditAllocation | null;
         currency: string;
         discount: Shared.Discount | null;
         external_price_id: string | null;
@@ -348,6 +394,10 @@ export declare namespace Price {
         interface BillableMetric {
             id: string;
         }
+        interface CreditAllocation {
+            allows_rollover: boolean;
+            currency: string;
+        }
         interface Item {
             id: string;
             name: string;
@@ -383,14 +433,16 @@ export declare namespace Price {
              * An integer amount to represent package size. For example, 1000 here would divide
              * usage by 1000 before multiplying by package_amount in rating
              */
-            package_size?: number | null;
+            package_size: number;
         }
     }
     interface MatrixPrice {
         id: string;
         billable_metric: MatrixPrice.BillableMetric | null;
         cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
+        conversion_rate: number | null;
         created_at: string;
+        credit_allocation: MatrixPrice.CreditAllocation | null;
         currency: string;
         discount: Shared.Discount | null;
         external_price_id: string | null;
@@ -410,6 +462,10 @@ export declare namespace Price {
         interface BillableMetric {
             id: string;
         }
+        interface CreditAllocation {
+            allows_rollover: boolean;
+            currency: string;
+        }
         interface Item {
             id: string;
             name: string;
@@ -469,7 +525,9 @@ export declare namespace Price {
         id: string;
         billable_metric: TieredPrice.BillableMetric | null;
         cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
+        conversion_rate: number | null;
         created_at: string;
+        credit_allocation: TieredPrice.CreditAllocation | null;
         currency: string;
         discount: Shared.Discount | null;
         external_price_id: string | null;
@@ -489,6 +547,10 @@ export declare namespace Price {
         interface BillableMetric {
             id: string;
         }
+        interface CreditAllocation {
+            allows_rollover: boolean;
+            currency: string;
+        }
         interface Item {
             id: string;
             name: string;
@@ -542,7 +604,9 @@ export declare namespace Price {
         id: string;
         billable_metric: TieredBpsPrice.BillableMetric | null;
         cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
+        conversion_rate: number | null;
         created_at: string;
+        credit_allocation: TieredBpsPrice.CreditAllocation | null;
         currency: string;
         discount: Shared.Discount | null;
         external_price_id: string | null;
@@ -562,6 +626,10 @@ export declare namespace Price {
         interface BillableMetric {
             id: string;
         }
+        interface CreditAllocation {
+            allows_rollover: boolean;
+            currency: string;
+        }
         interface Item {
             id: string;
             name: string;
@@ -621,7 +689,9 @@ export declare namespace Price {
         billable_metric: BpsPrice.BillableMetric | null;
         bps_config: BpsPrice.BpsConfig;
         cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
+        conversion_rate: number | null;
         created_at: string;
+        credit_allocation: BpsPrice.CreditAllocation | null;
         currency: string;
         discount: Shared.Discount | null;
         external_price_id: string | null;
@@ -650,6 +720,10 @@ export declare namespace Price {
              */
             per_unit_maximum?: string | null;
         }
+        interface CreditAllocation {
+            allows_rollover: boolean;
+            currency: string;
+        }
         interface Item {
             id: string;
             name: string;
@@ -682,7 +756,9 @@ export declare namespace Price {
         billable_metric: BulkBpsPrice.BillableMetric | null;
         bulk_bps_config: BulkBpsPrice.BulkBpsConfig;
         cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
+        conversion_rate: number | null;
         created_at: string;
+        credit_allocation: BulkBpsPrice.CreditAllocation | null;
         currency: string;
         discount: Shared.Discount | null;
         external_price_id: string | null;
@@ -724,6 +800,10 @@ export declare namespace Price {
                 per_unit_maximum?: string | null;
             }
         }
+        interface CreditAllocation {
+            allows_rollover: boolean;
+            currency: string;
+        }
         interface Item {
             id: string;
             name: string;
@@ -756,7 +836,9 @@ export declare namespace Price {
         billable_metric: BulkPrice.BillableMetric | null;
         bulk_config: BulkPrice.BulkConfig;
         cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
+        conversion_rate: number | null;
         created_at: string;
+        credit_allocation: BulkPrice.CreditAllocation | null;
         currency: string;
         discount: Shared.Discount | null;
         external_price_id: string | null;
@@ -793,6 +875,10 @@ export declare namespace Price {
                 maximum_units?: number | null;
             }
         }
+        interface CreditAllocation {
+            allows_rollover: boolean;
+            currency: string;
+        }
         interface Item {
             id: string;
             name: string;
@@ -824,7 +910,9 @@ export declare namespace Price {
         id: string;
         billable_metric: ThresholdTotalAmountPrice.BillableMetric | null;
         cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
+        conversion_rate: number | null;
         created_at: string;
+        credit_allocation: ThresholdTotalAmountPrice.CreditAllocation | null;
         currency: string;
         discount: Shared.Discount | null;
         external_price_id: string | null;
@@ -844,6 +932,10 @@ export declare namespace Price {
         interface BillableMetric {
             id: string;
         }
+        interface CreditAllocation {
+            allows_rollover: boolean;
+            currency: string;
+        }
         interface Item {
             id: string;
             name: string;
@@ -875,7 +967,9 @@ export declare namespace Price {
         id: string;
         billable_metric: TieredPackagePrice.BillableMetric | null;
         cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
+        conversion_rate: number | null;
         created_at: string;
+        credit_allocation: TieredPackagePrice.CreditAllocation | null;
         currency: string;
         discount: Shared.Discount | null;
         external_price_id: string | null;
@@ -895,6 +989,10 @@ export declare namespace Price {
         interface BillableMetric {
             id: string;
         }
+        interface CreditAllocation {
+            allows_rollover: boolean;
+            currency: string;
+        }
         interface Item {
             id: string;
             name: string;
@@ -926,7 +1024,9 @@ export declare namespace Price {
         id: string;
         billable_metric: GroupedTieredPrice.BillableMetric | null;
         cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
+        conversion_rate: number | null;
         created_at: string;
+        credit_allocation: GroupedTieredPrice.CreditAllocation | null;
         currency: string;
         discount: Shared.Discount | null;
         external_price_id: string | null;
@@ -946,6 +1046,10 @@ export declare namespace Price {
         interface BillableMetric {
             id: string;
         }
+        interface CreditAllocation {
+            allows_rollover: boolean;
+            currency: string;
+        }
         interface Item {
             id: string;
             name: string;
@@ -977,7 +1081,9 @@ export declare namespace Price {
         id: string;
         billable_metric: TieredWithMinimumPrice.BillableMetric | null;
         cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
+        conversion_rate: number | null;
         created_at: string;
+        credit_allocation: TieredWithMinimumPrice.CreditAllocation | null;
         currency: string;
         discount: Shared.Discount | null;
         external_price_id: string | null;
@@ -997,6 +1103,10 @@ export declare namespace Price {
         interface BillableMetric {
             id: string;
         }
+        interface CreditAllocation {
+            allows_rollover: boolean;
+            currency: string;
+        }
         interface Item {
             id: string;
             name: string;
@@ -1028,7 +1138,9 @@ export declare namespace Price {
         id: string;
         billable_metric: TieredPackageWithMinimumPrice.BillableMetric | null;
         cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
+        conversion_rate: number | null;
         created_at: string;
+        credit_allocation: TieredPackageWithMinimumPrice.CreditAllocation | null;
         currency: string;
         discount: Shared.Discount | null;
         external_price_id: string | null;
@@ -1048,6 +1160,10 @@ export declare namespace Price {
         interface BillableMetric {
             id: string;
         }
+        interface CreditAllocation {
+            allows_rollover: boolean;
+            currency: string;
+        }
         interface Item {
             id: string;
             name: string;
@@ -1079,7 +1195,9 @@ export declare namespace Price {
         id: string;
         billable_metric: PackageWithAllocationPrice.BillableMetric | null;
         cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
+        conversion_rate: number | null;
         created_at: string;
+        credit_allocation: PackageWithAllocationPrice.CreditAllocation | null;
         currency: string;
         discount: Shared.Discount | null;
         external_price_id: string | null;
@@ -1099,6 +1217,10 @@ export declare namespace Price {
         interface BillableMetric {
             id: string;
         }
+        interface CreditAllocation {
+            allows_rollover: boolean;
+            currency: string;
+        }
         interface Item {
             id: string;
             name: string;
@@ -1130,7 +1252,9 @@ export declare namespace Price {
         id: string;
         billable_metric: UnitWithPercentPrice.BillableMetric | null;
         cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
+        conversion_rate: number | null;
         created_at: string;
+        credit_allocation: UnitWithPercentPrice.CreditAllocation | null;
         currency: string;
         discount: Shared.Discount | null;
         external_price_id: string | null;
@@ -1150,6 +1274,10 @@ export declare namespace Price {
         interface BillableMetric {
             id: string;
         }
+        interface CreditAllocation {
+            allows_rollover: boolean;
+            currency: string;
+        }
         interface Item {
             id: string;
             name: string;
@@ -1181,7 +1309,9 @@ export declare namespace Price {
         id: string;
         billable_metric: MatrixWithAllocationPrice.BillableMetric | null;
         cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
+        conversion_rate: number | null;
         created_at: string;
+        credit_allocation: MatrixWithAllocationPrice.CreditAllocation | null;
         currency: string;
         discount: Shared.Discount | null;
         external_price_id: string | null;
@@ -1201,6 +1331,10 @@ export declare namespace Price {
         interface BillableMetric {
             id: string;
         }
+        interface CreditAllocation {
+            allows_rollover: boolean;
+            currency: string;
+        }
         interface Item {
             id: string;
             name: string;
@@ -1261,6 +1395,9 @@ export declare namespace Price {
         }
     }
 }
+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 {
@@ -1292,6 +1429,10 @@ export declare namespace PriceCreateParams {
          * this is true, and in-arrears if this is false.
          */
         billed_in_advance?: boolean | null;
+        /**
+         * The per unit conversion rate of the price currency to the invoicing currency.
+         */
+        conversion_rate?: number | null;
         /**
          * An alias for the price.
          */
@@ -1343,6 +1484,10 @@ export declare namespace PriceCreateParams {
          * this is true, and in-arrears if this is false.
          */
         billed_in_advance?: boolean | null;
+        /**
+         * The per unit conversion rate of the price currency to the invoicing currency.
+         */
+        conversion_rate?: number | null;
         /**
          * An alias for the price.
          */
@@ -1367,7 +1512,7 @@ export declare namespace PriceCreateParams {
              * An integer amount to represent package size. For example, 1000 here would divide
              * usage by 1000 before multiplying by package_amount in rating
              */
-            package_size?: number | null;
+            package_size: number;
         }
     }
     interface NewFloatingMatrixPrice {
@@ -1399,6 +1544,10 @@ export declare namespace PriceCreateParams {
          * this is true, and in-arrears if this is false.
          */
         billed_in_advance?: boolean | null;
+        /**
+         * The per unit conversion rate of the price currency to the invoicing currency.
+         */
+        conversion_rate?: number | null;
         /**
          * An alias for the price.
          */
@@ -1472,6 +1621,10 @@ export declare namespace PriceCreateParams {
          * this is true, and in-arrears if this is false.
          */
         billed_in_advance?: boolean | null;
+        /**
+         * The per unit conversion rate of the price currency to the invoicing currency.
+         */
+        conversion_rate?: number | null;
         /**
          * An alias for the price.
          */
@@ -1549,6 +1702,10 @@ export declare namespace PriceCreateParams {
          * this is true, and in-arrears if this is false.
          */
         billed_in_advance?: boolean | null;
+        /**
+         * The per unit conversion rate of the price currency to the invoicing currency.
+         */
+        conversion_rate?: number | null;
         /**
          * An alias for the price.
          */
@@ -1616,6 +1773,10 @@ export declare namespace PriceCreateParams {
          * this is true, and in-arrears if this is false.
          */
         billed_in_advance?: boolean | null;
+        /**
+         * The per unit conversion rate of the price currency to the invoicing currency.
+         */
+        conversion_rate?: number | null;
         /**
          * An alias for the price.
          */
@@ -1688,6 +1849,10 @@ export declare namespace PriceCreateParams {
          * this is true, and in-arrears if this is false.
          */
         billed_in_advance?: boolean | null;
+        /**
+         * The per unit conversion rate of the price currency to the invoicing currency.
+         */
+        conversion_rate?: number | null;
         /**
          * An alias for the price.
          */
@@ -1743,6 +1908,10 @@ export declare namespace PriceCreateParams {
          * this is true, and in-arrears if this is false.
          */
         billed_in_advance?: boolean | null;
+        /**
+         * The per unit conversion rate of the price currency to the invoicing currency.
+         */
+        conversion_rate?: number | null;
         /**
          * An alias for the price.
          */
@@ -1811,6 +1980,10 @@ export declare namespace PriceCreateParams {
          * this is true, and in-arrears if this is false.
          */
         billed_in_advance?: boolean | null;
+        /**
+         * The per unit conversion rate of the price currency to the invoicing currency.
+         */
+        conversion_rate?: number | null;
         /**
          * An alias for the price.
          */
@@ -1874,6 +2047,10 @@ export declare namespace PriceCreateParams {
          * this is true, and in-arrears if this is false.
          */
         billed_in_advance?: boolean | null;
+        /**
+         * The per unit conversion rate of the price currency to the invoicing currency.
+         */
+        conversion_rate?: number | null;
         /**
          * An alias for the price.
          */
@@ -1917,6 +2094,10 @@ export declare namespace PriceCreateParams {
          * this is true, and in-arrears if this is false.
          */
         billed_in_advance?: boolean | null;
+        /**
+         * The per unit conversion rate of the price currency to the invoicing currency.
+         */
+        conversion_rate?: number | null;
         /**
          * An alias for the price.
          */
@@ -1960,6 +2141,10 @@ export declare namespace PriceCreateParams {
          * this is true, and in-arrears if this is false.
          */
         billed_in_advance?: boolean | null;
+        /**
+         * The per unit conversion rate of the price currency to the invoicing currency.
+         */
+        conversion_rate?: number | null;
         /**
          * An alias for the price.
          */
@@ -2003,6 +2188,10 @@ export declare namespace PriceCreateParams {
          * this is true, and in-arrears if this is false.
          */
         billed_in_advance?: boolean | null;
+        /**
+         * The per unit conversion rate of the price currency to the invoicing currency.
+         */
+        conversion_rate?: number | null;
         /**
          * An alias for the price.
          */
@@ -2046,6 +2235,10 @@ export declare namespace PriceCreateParams {
          * this is true, and in-arrears if this is false.
          */
         billed_in_advance?: boolean | null;
+        /**
+         * The per unit conversion rate of the price currency to the invoicing currency.
+         */
+        conversion_rate?: number | null;
         /**
          * An alias for the price.
          */
@@ -2089,6 +2282,10 @@ export declare namespace PriceCreateParams {
          * this is true, and in-arrears if this is false.
          */
         billed_in_advance?: boolean | null;
+        /**
+         * The per unit conversion rate of the price currency to the invoicing currency.
+         */
+        conversion_rate?: number | null;
         /**
          * An alias for the price.
          */
@@ -2132,6 +2329,10 @@ export declare namespace PriceCreateParams {
          * this is true, and in-arrears if this is false.
          */
         billed_in_advance?: boolean | null;
+        /**
+         * The per unit conversion rate of the price currency to the invoicing currency.
+         */
+        conversion_rate?: number | null;
         /**
          * An alias for the price.
          */
@@ -2149,11 +2350,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