feat(api): price evaluation endpoint generally available

api.md

@@ -255,12 +255,15 @@ Methods:
 
 Types:
 
+- <code><a href="./src/resources/prices/prices.ts">EvaluatePriceGroup</a></code>
 - <code><a href="./src/resources/prices/prices.ts">Price</a></code>
+- <code><a href="./src/resources/prices/prices.ts">PriceEvaluateResponse</a></code>
 
 Methods:
 
 - <code title="post /prices">client.prices.<a href="./src/resources/prices/prices.ts">create</a>({ ...params }) -> Price</code>
 - <code title="get /prices">client.prices.<a href="./src/resources/prices/prices.ts">list</a>({ ...params }) -> PricesPage</code>
+- <code title="post /prices/{price_id}/evaluate">client.prices.<a href="./src/resources/prices/prices.ts">evaluate</a>(priceId, { ...params }) -> PriceEvaluateResponse</code>
 - <code title="get /prices/{price_id}">client.prices.<a href="./src/resources/prices/prices.ts">fetch</a>(priceId) -> Price</code>
 
 ## ExternalPriceID
@@ -296,16 +299,3 @@ Methods:
 - <code title="post /subscriptions/{subscription_id}/unschedule_fixed_fee_quantity_updates">client.subscriptions.<a href="./src/resources/subscriptions.ts">unscheduleFixedFeeQuantityUpdates</a>(subscriptionId, { ...params }) -> Subscription</code>
 - <code title="post /subscriptions/{subscription_id}/unschedule_pending_plan_changes">client.subscriptions.<a href="./src/resources/subscriptions.ts">unschedulePendingPlanChanges</a>(subscriptionId) -> Subscription</code>
 - <code title="post /subscriptions/{subscription_id}/update_fixed_fee_quantity">client.subscriptions.<a href="./src/resources/subscriptions.ts">updateFixedFeeQuantity</a>(subscriptionId, { ...params }) -> Subscription</code>
-
-# Beta
-
-## Price
-
-Types:
-
-- <code><a href="./src/resources/beta/price.ts">EvaluatePriceGroup</a></code>
-- <code><a href="./src/resources/beta/price.ts">PriceEvaluateResponse</a></code>
-
-Methods:
-
-- <code title="post /prices/{price_id}/evaluate">client.beta.price.<a href="./src/resources/beta/price.ts">evaluate</a>(priceId, { ...params }) -> PriceEvaluateResponse</code>

src/index.ts

@@ -141,7 +141,6 @@ export class Orb extends Core.APIClient {
   plans: API.Plans = new API.Plans(this);
   prices: API.Prices = new API.Prices(this);
   subscriptions: API.Subscriptions = new API.Subscriptions(this);
-  beta: API.Beta = new API.Beta(this);
 
   protected override defaultQuery(): Core.DefaultQuery | undefined {
     return this._options.defaultQuery;
@@ -298,10 +297,13 @@ export namespace Orb {
   export import PlanListParams = API.PlanListParams;
 
   export import Prices = API.Prices;
+  export import EvaluatePriceGroup = API.EvaluatePriceGroup;
   export import Price = API.Price;
+  export import PriceEvaluateResponse = API.PriceEvaluateResponse;
   export import PricesPage = API.PricesPage;
   export import PriceCreateParams = API.PriceCreateParams;
   export import PriceListParams = API.PriceListParams;
+  export import PriceEvaluateParams = API.PriceEvaluateParams;
 
   export import Subscriptions = API.Subscriptions;
   export import Subscription = API.Subscription;
@@ -323,8 +325,6 @@ export namespace Orb {
   export import SubscriptionUnscheduleFixedFeeQuantityUpdatesParams = API.SubscriptionUnscheduleFixedFeeQuantityUpdatesParams;
   export import SubscriptionUpdateFixedFeeQuantityParams = API.SubscriptionUpdateFixedFeeQuantityParams;
 
-  export import Beta = API.Beta;
-
   export import BillingCycleRelativeDate = API.BillingCycleRelativeDate;
   export import Discount = API.Discount;
   export import PaginationMetadata = API.PaginationMetadata;

src/resources/index.ts

@@ -1,7 +1,6 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 export * from './shared';
-export { Beta } from './beta/beta';
 export { Coupon, CouponCreateParams, CouponListParams, CouponsPage, Coupons } from './coupons/coupons';
 export { CreditNote, CreditNoteListParams, CreditNotesPage, CreditNotes } from './credit-notes';
 export {
@@ -13,6 +12,16 @@ export {
   CustomersPage,
   Customers,
 } from './customers/customers';
+export {
+  EvaluatePriceGroup,
+  Price,
+  PriceEvaluateResponse,
+  PriceCreateParams,
+  PriceListParams,
+  PriceEvaluateParams,
+  PricesPage,
+  Prices,
+} from './prices/prices';
 export {
   EventUpdateResponse,
   EventDeprecateResponse,
@@ -49,7 +58,6 @@ export {
   Metrics,
 } from './metrics';
 export { Plan, PlanCreateParams, PlanUpdateParams, PlanListParams, PlansPage, Plans } from './plans/plans';
-export { Price, PriceCreateParams, PriceListParams, PricesPage, Prices } from './prices/prices';
 export {
   Subscription,
   SubscriptionUsage,

src/resources/prices/index.ts

@@ -1,4 +1,13 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+export {
+  EvaluatePriceGroup,
+  Price,
+  PriceEvaluateResponse,
+  PriceCreateParams,
+  PriceListParams,
+  PriceEvaluateParams,
+  PricesPage,
+  Prices,
+} from './prices';
 export { ExternalPriceID } from './external-price-id';
-export { Price, PriceCreateParams, PriceListParams, PricesPage, Prices } from './prices';

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
@@ -1859,6 +1907,10 @@ export namespace Price {
   }
 }
 
+export interface PriceEvaluateResponse {
+  data: Array<EvaluatePriceGroup>;
+}
+
 export type PriceCreateParams =
   | PriceCreateParams.NewFloatingUnitPrice
   | PriceCreateParams.NewFloatingPackagePrice
@@ -2972,10 +3024,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;
 }