orb-billing 2.2.0 → 2.4.0

package/src/resources/prices/prices.ts

@@ -43,6 +43,37 @@ export class Prices extends APIResource {
     return this._client.getAPIList('/prices', PricesPage, { query, ...options });
   }
 
+  /**
+   * 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> {
+    return this._client.post(`/prices/${priceId}/evaluate`, { body, ...options });
+  }
+
   /**
    * This endpoint returns a price given an identifier.
    */
@@ -53,6 +84,23 @@ export class Prices extends APIResource {
 
 export 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
@@ -312,8 +360,12 @@ export namespace Price {
 
     cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
 
+    conversion_rate: number | null;
+
     created_at: string;
 
+    credit_allocation: UnitPrice.CreditAllocation | null;
+
     currency: string;
 
     discount: Shared.Discount | null;
@@ -348,6 +400,12 @@ export namespace Price {
       id: string;
     }
 
+    export interface CreditAllocation {
+      allows_rollover: boolean;
+
+      currency: string;
+    }
+
     export interface Item {
       id: string;
 
@@ -395,8 +453,12 @@ export namespace Price {
 
     cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
 
+    conversion_rate: number | null;
+
     created_at: string;
 
+    credit_allocation: PackagePrice.CreditAllocation | null;
+
     currency: string;
 
     discount: Shared.Discount | null;
@@ -431,6 +493,12 @@ export namespace Price {
       id: string;
     }
 
+    export interface CreditAllocation {
+      allows_rollover: boolean;
+
+      currency: string;
+    }
+
     export interface Item {
       id: string;
 
@@ -473,7 +541,7 @@ export 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;
     }
   }
 
@@ -484,8 +552,12 @@ export namespace Price {
 
     cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
 
+    conversion_rate: number | null;
+
     created_at: string;
 
+    credit_allocation: MatrixPrice.CreditAllocation | null;
+
     currency: string;
 
     discount: Shared.Discount | null;
@@ -520,6 +592,12 @@ export namespace Price {
       id: string;
     }
 
+    export interface CreditAllocation {
+      allows_rollover: boolean;
+
+      currency: string;
+    }
+
     export interface Item {
       id: string;
 
@@ -593,8 +671,12 @@ export namespace Price {
 
     cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
 
+    conversion_rate: number | null;
+
     created_at: string;
 
+    credit_allocation: TieredPrice.CreditAllocation | null;
+
     currency: string;
 
     discount: Shared.Discount | null;
@@ -629,6 +711,12 @@ export namespace Price {
       id: string;
     }
 
+    export interface CreditAllocation {
+      allows_rollover: boolean;
+
+      currency: string;
+    }
+
     export interface Item {
       id: string;
 
@@ -695,8 +783,12 @@ export namespace Price {
 
     cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
 
+    conversion_rate: number | null;
+
     created_at: string;
 
+    credit_allocation: TieredBpsPrice.CreditAllocation | null;
+
     currency: string;
 
     discount: Shared.Discount | null;
@@ -731,6 +823,12 @@ export namespace Price {
       id: string;
     }
 
+    export interface CreditAllocation {
+      allows_rollover: boolean;
+
+      currency: string;
+    }
+
     export interface Item {
       id: string;
 
@@ -805,8 +903,12 @@ export namespace Price {
 
     cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
 
+    conversion_rate: number | null;
+
     created_at: string;
 
+    credit_allocation: BpsPrice.CreditAllocation | null;
+
     currency: string;
 
     discount: Shared.Discount | null;
@@ -851,6 +953,12 @@ export namespace Price {
       per_unit_maximum?: string | null;
     }
 
+    export interface CreditAllocation {
+      allows_rollover: boolean;
+
+      currency: string;
+    }
+
     export interface Item {
       id: string;
 
@@ -893,8 +1001,12 @@ export namespace Price {
 
     cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
 
+    conversion_rate: number | null;
+
     created_at: string;
 
+    credit_allocation: BulkBpsPrice.CreditAllocation | null;
+
     currency: string;
 
     discount: Shared.Discount | null;
@@ -954,6 +1066,12 @@ export namespace Price {
       }
     }
 
+    export interface CreditAllocation {
+      allows_rollover: boolean;
+
+      currency: string;
+    }
+
     export interface Item {
       id: string;
 
@@ -996,8 +1114,12 @@ export namespace Price {
 
     cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
 
+    conversion_rate: number | null;
+
     created_at: string;
 
+    credit_allocation: BulkPrice.CreditAllocation | null;
+
     currency: string;
 
     discount: Shared.Discount | null;
@@ -1051,6 +1173,12 @@ export namespace Price {
       }
     }
 
+    export interface CreditAllocation {
+      allows_rollover: boolean;
+
+      currency: string;
+    }
+
     export interface Item {
       id: string;
 
@@ -1091,8 +1219,12 @@ export namespace Price {
 
     cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
 
+    conversion_rate: number | null;
+
     created_at: string;
 
+    credit_allocation: ThresholdTotalAmountPrice.CreditAllocation | null;
+
     currency: string;
 
     discount: Shared.Discount | null;
@@ -1127,6 +1259,12 @@ export namespace Price {
       id: string;
     }
 
+    export interface CreditAllocation {
+      allows_rollover: boolean;
+
+      currency: string;
+    }
+
     export interface Item {
       id: string;
 
@@ -1167,8 +1305,12 @@ export namespace Price {
 
     cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
 
+    conversion_rate: number | null;
+
     created_at: string;
 
+    credit_allocation: TieredPackagePrice.CreditAllocation | null;
+
     currency: string;
 
     discount: Shared.Discount | null;
@@ -1203,6 +1345,12 @@ export namespace Price {
       id: string;
     }
 
+    export interface CreditAllocation {
+      allows_rollover: boolean;
+
+      currency: string;
+    }
+
     export interface Item {
       id: string;
 
@@ -1243,8 +1391,12 @@ export namespace Price {
 
     cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
 
+    conversion_rate: number | null;
+
     created_at: string;
 
+    credit_allocation: GroupedTieredPrice.CreditAllocation | null;
+
     currency: string;
 
     discount: Shared.Discount | null;
@@ -1279,6 +1431,12 @@ export namespace Price {
       id: string;
     }
 
+    export interface CreditAllocation {
+      allows_rollover: boolean;
+
+      currency: string;
+    }
+
     export interface Item {
       id: string;
 
@@ -1319,8 +1477,12 @@ export namespace Price {
 
     cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
 
+    conversion_rate: number | null;
+
     created_at: string;
 
+    credit_allocation: TieredWithMinimumPrice.CreditAllocation | null;
+
     currency: string;
 
     discount: Shared.Discount | null;
@@ -1355,6 +1517,12 @@ export namespace Price {
       id: string;
     }
 
+    export interface CreditAllocation {
+      allows_rollover: boolean;
+
+      currency: string;
+    }
+
     export interface Item {
       id: string;
 
@@ -1395,8 +1563,12 @@ export namespace Price {
 
     cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
 
+    conversion_rate: number | null;
+
     created_at: string;
 
+    credit_allocation: TieredPackageWithMinimumPrice.CreditAllocation | null;
+
     currency: string;
 
     discount: Shared.Discount | null;
@@ -1431,6 +1603,12 @@ export namespace Price {
       id: string;
     }
 
+    export interface CreditAllocation {
+      allows_rollover: boolean;
+
+      currency: string;
+    }
+
     export interface Item {
       id: string;
 
@@ -1471,8 +1649,12 @@ export namespace Price {
 
     cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
 
+    conversion_rate: number | null;
+
     created_at: string;
 
+    credit_allocation: PackageWithAllocationPrice.CreditAllocation | null;
+
     currency: string;
 
     discount: Shared.Discount | null;
@@ -1507,6 +1689,12 @@ export namespace Price {
       id: string;
     }
 
+    export interface CreditAllocation {
+      allows_rollover: boolean;
+
+      currency: string;
+    }
+
     export interface Item {
       id: string;
 
@@ -1547,8 +1735,12 @@ export namespace Price {
 
     cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
 
+    conversion_rate: number | null;
+
     created_at: string;
 
+    credit_allocation: UnitWithPercentPrice.CreditAllocation | null;
+
     currency: string;
 
     discount: Shared.Discount | null;
@@ -1583,6 +1775,12 @@ export namespace Price {
       id: string;
     }
 
+    export interface CreditAllocation {
+      allows_rollover: boolean;
+
+      currency: string;
+    }
+
     export interface Item {
       id: string;
 
@@ -1623,8 +1821,12 @@ export namespace Price {
 
     cadence: 'one_time' | 'monthly' | 'quarterly' | 'annual';
 
+    conversion_rate: number | null;
+
     created_at: string;
 
+    credit_allocation: MatrixWithAllocationPrice.CreditAllocation | null;
+
     currency: string;
 
     discount: Shared.Discount | null;
@@ -1659,6 +1861,12 @@ export namespace Price {
       id: string;
     }
 
+    export interface CreditAllocation {
+      allows_rollover: boolean;
+
+      currency: string;
+    }
+
     export interface Item {
       id: string;
 
@@ -1731,6 +1939,10 @@ export namespace Price {
   }
 }
 
+export interface PriceEvaluateResponse {
+  data: Array<EvaluatePriceGroup>;
+}
+
 export type PriceCreateParams =
   | PriceCreateParams.NewFloatingUnitPrice
   | PriceCreateParams.NewFloatingPackagePrice
@@ -1787,6 +1999,11 @@ export namespace PriceCreateParams {
      */
     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.
      */
@@ -1850,6 +2067,11 @@ export namespace PriceCreateParams {
      */
     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.
      */
@@ -1878,7 +2100,7 @@ export 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;
     }
   }
 
@@ -1919,6 +2141,11 @@ export namespace PriceCreateParams {
      */
     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.
      */
@@ -2008,6 +2235,11 @@ export namespace PriceCreateParams {
      */
     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.
      */
@@ -2102,6 +2334,11 @@ export namespace PriceCreateParams {
      */
     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.
      */
@@ -2184,6 +2421,11 @@ export namespace PriceCreateParams {
      */
     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.
      */
@@ -2272,6 +2514,11 @@ export namespace PriceCreateParams {
      */
     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.
      */
@@ -2340,6 +2587,11 @@ export namespace PriceCreateParams {
      */
     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.
      */
@@ -2423,6 +2675,11 @@ export namespace PriceCreateParams {
      */
     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.
      */
@@ -2500,6 +2757,11 @@ export namespace PriceCreateParams {
      */
     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.
      */
@@ -2554,6 +2816,11 @@ export namespace PriceCreateParams {
      */
     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.
      */
@@ -2608,6 +2875,11 @@ export namespace PriceCreateParams {
      */
     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.
      */
@@ -2662,6 +2934,11 @@ export namespace PriceCreateParams {
      */
     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.
      */
@@ -2716,6 +2993,11 @@ export namespace PriceCreateParams {
      */
     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.
      */
@@ -2770,6 +3052,11 @@ export namespace PriceCreateParams {
      */
     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.
      */
@@ -2824,6 +3111,11 @@ export namespace PriceCreateParams {
      */
     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.
      */
@@ -2844,10 +3136,49 @@ export 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 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;
 }