orb-billing 2.1.2 → 2.3.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
@@ -297,7 +345,9 @@ export type Price =
   | Price.BulkPrice
   | Price.ThresholdTotalAmountPrice
   | Price.TieredPackagePrice
+  | Price.GroupedTieredPrice
   | Price.TieredWithMinimumPrice
+  | Price.TieredPackageWithMinimumPrice
   | Price.PackageWithAllocationPrice
   | Price.UnitWithPercentPrice
   | Price.MatrixWithAllocationPrice;
@@ -312,6 +362,8 @@ export namespace Price {
 
     created_at: string;
 
+    credit_allocation: UnitPrice.CreditAllocation | null;
+
     currency: string;
 
     discount: Shared.Discount | null;
@@ -346,6 +398,12 @@ export namespace Price {
       id: string;
     }
 
+    export interface CreditAllocation {
+      allows_rollover: boolean;
+
+      currency: string;
+    }
+
     export interface Item {
       id: string;
 
@@ -395,6 +453,8 @@ export namespace Price {
 
     created_at: string;
 
+    credit_allocation: PackagePrice.CreditAllocation | null;
+
     currency: string;
 
     discount: Shared.Discount | null;
@@ -429,6 +489,12 @@ export namespace Price {
       id: string;
     }
 
+    export interface CreditAllocation {
+      allows_rollover: boolean;
+
+      currency: string;
+    }
+
     export interface Item {
       id: string;
 
@@ -484,6 +550,8 @@ export namespace Price {
 
     created_at: string;
 
+    credit_allocation: MatrixPrice.CreditAllocation | null;
+
     currency: string;
 
     discount: Shared.Discount | null;
@@ -518,6 +586,12 @@ export namespace Price {
       id: string;
     }
 
+    export interface CreditAllocation {
+      allows_rollover: boolean;
+
+      currency: string;
+    }
+
     export interface Item {
       id: string;
 
@@ -593,6 +667,8 @@ export namespace Price {
 
     created_at: string;
 
+    credit_allocation: TieredPrice.CreditAllocation | null;
+
     currency: string;
 
     discount: Shared.Discount | null;
@@ -627,6 +703,12 @@ export namespace Price {
       id: string;
     }
 
+    export interface CreditAllocation {
+      allows_rollover: boolean;
+
+      currency: string;
+    }
+
     export interface Item {
       id: string;
 
@@ -695,6 +777,8 @@ export namespace Price {
 
     created_at: string;
 
+    credit_allocation: TieredBpsPrice.CreditAllocation | null;
+
     currency: string;
 
     discount: Shared.Discount | null;
@@ -729,6 +813,12 @@ export namespace Price {
       id: string;
     }
 
+    export interface CreditAllocation {
+      allows_rollover: boolean;
+
+      currency: string;
+    }
+
     export interface Item {
       id: string;
 
@@ -805,6 +895,8 @@ export namespace Price {
 
     created_at: string;
 
+    credit_allocation: BpsPrice.CreditAllocation | null;
+
     currency: string;
 
     discount: Shared.Discount | null;
@@ -849,6 +941,12 @@ export namespace Price {
       per_unit_maximum?: string | null;
     }
 
+    export interface CreditAllocation {
+      allows_rollover: boolean;
+
+      currency: string;
+    }
+
     export interface Item {
       id: string;
 
@@ -893,6 +991,8 @@ export namespace Price {
 
     created_at: string;
 
+    credit_allocation: BulkBpsPrice.CreditAllocation | null;
+
     currency: string;
 
     discount: Shared.Discount | null;
@@ -952,6 +1052,12 @@ export namespace Price {
       }
     }
 
+    export interface CreditAllocation {
+      allows_rollover: boolean;
+
+      currency: string;
+    }
+
     export interface Item {
       id: string;
 
@@ -996,6 +1102,8 @@ export namespace Price {
 
     created_at: string;
 
+    credit_allocation: BulkPrice.CreditAllocation | null;
+
     currency: string;
 
     discount: Shared.Discount | null;
@@ -1049,6 +1157,12 @@ export namespace Price {
       }
     }
 
+    export interface CreditAllocation {
+      allows_rollover: boolean;
+
+      currency: string;
+    }
+
     export interface Item {
       id: string;
 
@@ -1091,6 +1205,8 @@ export namespace Price {
 
     created_at: string;
 
+    credit_allocation: ThresholdTotalAmountPrice.CreditAllocation | null;
+
     currency: string;
 
     discount: Shared.Discount | null;
@@ -1125,6 +1241,12 @@ export namespace Price {
       id: string;
     }
 
+    export interface CreditAllocation {
+      allows_rollover: boolean;
+
+      currency: string;
+    }
+
     export interface Item {
       id: string;
 
@@ -1167,6 +1289,8 @@ export namespace Price {
 
     created_at: string;
 
+    credit_allocation: TieredPackagePrice.CreditAllocation | null;
+
     currency: string;
 
     discount: Shared.Discount | null;
@@ -1201,6 +1325,96 @@ export namespace Price {
       id: string;
     }
 
+    export interface CreditAllocation {
+      allows_rollover: boolean;
+
+      currency: string;
+    }
+
+    export interface Item {
+      id: string;
+
+      name: string;
+    }
+
+    export 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;
+    }
+
+    export 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;
+    }
+  }
+
+  export 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';
+  }
+
+  export namespace GroupedTieredPrice {
+    export interface BillableMetric {
+      id: string;
+    }
+
+    export interface CreditAllocation {
+      allows_rollover: boolean;
+
+      currency: string;
+    }
+
     export interface Item {
       id: string;
 
@@ -1243,6 +1457,8 @@ export namespace Price {
 
     created_at: string;
 
+    credit_allocation: TieredWithMinimumPrice.CreditAllocation | null;
+
     currency: string;
 
     discount: Shared.Discount | null;
@@ -1277,6 +1493,96 @@ export namespace Price {
       id: string;
     }
 
+    export interface CreditAllocation {
+      allows_rollover: boolean;
+
+      currency: string;
+    }
+
+    export interface Item {
+      id: string;
+
+      name: string;
+    }
+
+    export 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;
+    }
+
+    export 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;
+    }
+  }
+
+  export 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>;
+  }
+
+  export namespace TieredPackageWithMinimumPrice {
+    export interface BillableMetric {
+      id: string;
+    }
+
+    export interface CreditAllocation {
+      allows_rollover: boolean;
+
+      currency: string;
+    }
+
     export interface Item {
       id: string;
 
@@ -1319,6 +1625,8 @@ export namespace Price {
 
     created_at: string;
 
+    credit_allocation: PackageWithAllocationPrice.CreditAllocation | null;
+
     currency: string;
 
     discount: Shared.Discount | null;
@@ -1353,6 +1661,12 @@ export namespace Price {
       id: string;
     }
 
+    export interface CreditAllocation {
+      allows_rollover: boolean;
+
+      currency: string;
+    }
+
     export interface Item {
       id: string;
 
@@ -1395,6 +1709,8 @@ export namespace Price {
 
     created_at: string;
 
+    credit_allocation: UnitWithPercentPrice.CreditAllocation | null;
+
     currency: string;
 
     discount: Shared.Discount | null;
@@ -1429,6 +1745,12 @@ export namespace Price {
       id: string;
     }
 
+    export interface CreditAllocation {
+      allows_rollover: boolean;
+
+      currency: string;
+    }
+
     export interface Item {
       id: string;
 
@@ -1471,6 +1793,8 @@ export namespace Price {
 
     created_at: string;
 
+    credit_allocation: MatrixWithAllocationPrice.CreditAllocation | null;
+
     currency: string;
 
     discount: Shared.Discount | null;
@@ -1505,6 +1829,12 @@ export namespace Price {
       id: string;
     }
 
+    export interface CreditAllocation {
+      allows_rollover: boolean;
+
+      currency: string;
+    }
+
     export interface Item {
       id: string;
 
@@ -1577,6 +1907,10 @@ export namespace Price {
   }
 }
 
+export interface PriceEvaluateResponse {
+  data: Array<EvaluatePriceGroup>;
+}
+
 export type PriceCreateParams =
   | PriceCreateParams.NewFloatingUnitPrice
   | PriceCreateParams.NewFloatingPackagePrice
@@ -1589,6 +1923,7 @@ export type PriceCreateParams =
   | PriceCreateParams.NewFloatingBulkPrice
   | PriceCreateParams.NewFloatingThresholdTotalAmountPrice
   | PriceCreateParams.NewFloatingTieredPackagePrice
+  | PriceCreateParams.NewFloatingGroupedTieredPrice
   | PriceCreateParams.NewFloatingTieredWithMinimumPrice
   | PriceCreateParams.NewFloatingPackageWithAllocationPrice
   | PriceCreateParams.NewFloatingTieredPackageWithMinimumPrice
@@ -2416,6 +2751,60 @@ export namespace PriceCreateParams {
     invoice_grouping_key?: string | null;
   }
 
+  export 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;
+  }
+
   export interface NewFloatingTieredWithMinimumPrice {
     /**
      * The cadence to bill for this price on.
@@ -2635,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;
 }

package/src/resources/shared.ts

@@ -1,5 +1,7 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+export type BillingCycleRelativeDate = 'start_of_term' | 'end_of_term';
+
 export type Discount =
   | Discount.PercentageDiscount
   | Discount.TrialDiscount
@@ -82,3 +84,9 @@ export namespace Discount {
     reason?: string | null;
   }
 }
+
+export interface PaginationMetadata {
+  has_more: boolean;
+
+  next_cursor: string | null;
+}