orb-billing 1.37.4 → 1.39.0

package/src/resources/customers/costs.ts

@@ -326,7 +326,7 @@ export interface CostListResponse {
 
 export namespace CostListResponse {
   export interface Data {
-    per_price_costs: Array<Data.PerPriceCost>;
+    per_price_costs: Array<Data.PerPriceCost | Data.PerPriceCostV2>;
 
     /**
      * Total costs for the timeframe, excluding any minimums and discounts.
@@ -625,34 +625,598 @@ export namespace CostListResponse {
         total: string;
       }
     }
+
+    export interface PerPriceCostV2 {
+      /**
+       * 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
+       * take a quantity and determine an amount to bill.
+       *
+       * Orb supports a few different pricing models out of the box. Each of these models
+       * is serialized differently in a given Price object. The model_type field
+       * determines the key for the configuration object that is present.
+       *
+       * ## Unit pricing
+       *
+       * With unit pricing, each unit costs a fixed amount.
+       *
+       * ```json
+       * {
+       *     ...
+       *     "model_type": "unit",
+       *     "unit_config": {
+       *         "unit_amount": "0.50"
+       *     }
+       *     ...
+       * }
+       * ```
+       *
+       * ## Tiered pricing
+       *
+       * In tiered pricing, the cost of a given unit depends on the tier range that it
+       * falls into, where each tier range is defined by an upper and lower bound. For
+       * example, the first ten units may cost $0.50 each and all units thereafter may
+       * cost $0.10 each.
+       *
+       * ```json
+       * {
+       *     ...
+       *     "model_type": "tiered",
+       *     "tiered_config": {
+       *         "tiers": [
+       *             {
+       *                 "first_unit": 1,
+       *                 "last_unit": 10,
+       *                 "unit_amount": "0.50"
+       *             },
+       *             {
+       *                 "first_unit": 11,
+       *                 "last_unit": null,
+       *                 "unit_amount": "0.10"
+       *             }
+       *         ]
+       *     }
+       *     ...
+       * ```
+       *
+       * ## Bulk pricing
+       *
+       * Bulk pricing applies when the number of units determine the cost of all units.
+       * For example, if you've bought less than 10 units, they may each be $0.50 for a
+       * total of $5.00. Once you've bought more than 10 units, all units may now be
+       * priced at $0.40 (i.e. 101 units total would be $40.40).
+       *
+       * ```json
+       * {
+       *     ...
+       *     "model_type": "bulk",
+       *     "bulk_config": {
+       *         "tiers": [
+       *             {
+       *                 "maximum_units": 10,
+       *                 "unit_amount": "0.50"
+       *             },
+       *             {
+       *                 "maximum_units": 1000,
+       *                 "unit_amount": "0.40"
+       *             }
+       *         ]
+       *     }
+       *     ...
+       * }
+       * ```
+       *
+       * ## Package pricing
+       *
+       * Package pricing defines the size or granularity of a unit for billing purposes.
+       * For example, if the package size is set to 5, then 4 units will be billed as 5
+       * and 6 units will be billed at 10.
+       *
+       * ```json
+       * {
+       *     ...
+       *     "model_type": "package",
+       *     "package_config": {
+       *         "package_amount": "0.80",
+       *         "package_size": 10
+       *     }
+       *     ...
+       * }
+       * ```
+       *
+       * ## BPS pricing
+       *
+       * BPS pricing specifies a per-event (e.g. per-payment) rate in one hundredth of a
+       * percent (the number of basis points to charge), as well as a cap per event to
+       * assess. For example, this would allow you to assess a fee of 0.25% on every
+       * payment you process, with a maximum charge of $25 per payment.
+       *
+       * ```json
+       * {
+       *     ...
+       *     "model_type": "bps",
+       *     "bps_config": {
+       *        "bps": 125,
+       *        "per_unit_maximum": "11.00"
+       *     }
+       *     ...
+       *  }
+       * ```
+       *
+       * ## Bulk BPS pricing
+       *
+       * Bulk BPS pricing specifies BPS parameters in a tiered manner, dependent on the
+       * total quantity across all events. Similar to bulk pricing, the BPS parameters of
+       * a given event depends on the tier range that the billing period falls into. Each
+       * tier range is defined by an upper bound. For example, after $1.5M of payment
+       * volume is reached, each individual payment may have a lower cap or a smaller
+       * take-rate.
+       *
+       * ```json
+       *     ...
+       *     "model_type": "bulk_bps",
+       *     "bulk_bps_config": {
+       *         "tiers": [
+       *            {
+       *                 "maximum_amount": "1000000.00",
+       *                 "bps": 125,
+       *                 "per_unit_maximum": "19.00"
+       *            },
+       *           {
+       *                 "maximum_amount": null,
+       *                 "bps": 115,
+       *                 "per_unit_maximum": "4.00"
+       *             }
+       *         ]
+       *     }
+       *     ...
+       * }
+       * ```
+       *
+       * ## Tiered BPS pricing
+       *
+       * Tiered BPS pricing specifies BPS parameters in a graduated manner, where an
+       * event's applicable parameter is a function of its marginal addition to the
+       * period total. Similar to tiered pricing, the BPS parameters of a given event
+       * depends on the tier range that it falls into, where each tier range is defined
+       * by an upper and lower bound. For example, the first few payments may have a 0.8
+       * BPS take-rate and all payments after a specific volume may incur a take-rate of
+       * 0.5 BPS each.
+       *
+       * ```json
+       *     ...
+       *     "model_type": "tiered_bps",
+       *     "tiered_bps_config": {
+       *         "tiers": [
+       *            {
+       *                 "minimum_amount": "0",
+       *                 "maximum_amount": "1000000.00",
+       *                 "bps": 125,
+       *                 "per_unit_maximum": "19.00"
+       *            },
+       *           {
+       *                 "minimum_amount": "1000000.00",
+       *                 "maximum_amount": null,
+       *                 "bps": 115,
+       *                 "per_unit_maximum": "4.00"
+       *             }
+       *         ]
+       *     }
+       *     ...
+       * }
+       * ```
+       *
+       * ## Matrix pricing
+       *
+       * Matrix pricing defines a set of unit prices in a one or two-dimensional matrix.
+       * `dimensions` defines the two event property values evaluated in this pricing
+       * model. In a one-dimensional matrix, the second value is `null`. Every
+       * configuration has a list of `matrix_values` which give the unit prices for
+       * specified property values. In a one-dimensional matrix, the matrix values will
+       * have `dimension_values` where the second value of the pair is null. If an event
+       * does not match any of the dimension values in the matrix, it will resort to the
+       * `default_unit_amount`.
+       *
+       * ```json
+       * {
+       *     "model_type": "matrix"
+       *     "matrix_config": {
+       *         "default_unit_amount": "3.00",
+       *         "dimensions": [
+       *             "cluster_name",
+       *             "region"
+       *         ],
+       *         "matrix_values": [
+       *             {
+       *                 "dimension_values": [
+       *                     "alpha",
+       *                     "west"
+       *                 ],
+       *                 "unit_amount": "2.00"
+       *             },
+       *             ...
+       *         ]
+       *     }
+       * }
+       * ```
+       *
+       * ### Fixed fees
+       *
+       * Fixed fees are prices that are applied independent of usage quantities, and
+       * follow unit pricing. They also have an additional parameter
+       * `fixed_price_quantity`. If the Price represents a fixed cost, this represents
+       * the quantity of units applied.
+       *
+       * ```json
+       * {
+       *     ...
+       *     "id": "price_id",
+       *     "model_type": "unit",
+       *     "unit_config": {
+       *        "unit_amount": "2.00"
+       *     },
+       *     "fixed_price_quantity": 3.0
+       *     ...
+       * }
+       * ```
+       */
+      price: PricesAPI.Price;
+
+      /**
+       * Price's contributions for the timeframe, excluding any minimums and discounts.
+       */
+      subtotal: string;
+
+      /**
+       * Price's contributions for the timeframe, including minimums and discounts.
+       */
+      total: string;
+
+      /**
+       * If a `group_by` attribute is passed in, array of costs per `grouping_key`,
+       * `grouping_value` or `secondary_grouping_key`, `secondary_grouping_value`.
+       */
+      price_groups?: Array<PerPriceCostV2.PriceGroup> | null;
+
+      /**
+       * The price's quantity for the timeframe
+       */
+      quantity?: number | null;
+    }
+
+    export namespace PerPriceCostV2 {
+      export interface PriceGroup {
+        /**
+         * Grouping key to break down a single price's costs
+         */
+        grouping_key: string;
+
+        grouping_value: string | null;
+
+        /**
+         * If the price is a matrix price, this is the second dimension key
+         */
+        secondary_grouping_key: string | null;
+
+        secondary_grouping_value: string | null;
+
+        /**
+         * Total costs for this group for the timeframe. Note that this does not account
+         * for any minimums or discounts.
+         */
+        total: string;
+      }
+    }
   }
 }
 
-export interface CostListByExternalIDResponse {
-  data: Array<CostListByExternalIDResponse.Data>;
-}
+export interface CostListByExternalIDResponse {
+  data: Array<CostListByExternalIDResponse.Data>;
+}
+
+export namespace CostListByExternalIDResponse {
+  export interface Data {
+    per_price_costs: Array<Data.PerPriceCost | Data.PerPriceCostV2>;
+
+    /**
+     * Total costs for the timeframe, excluding any minimums and discounts.
+     */
+    subtotal: string;
+
+    timeframe_end: string;
+
+    timeframe_start: string;
+
+    /**
+     * Total costs for the timeframe, including any minimums and discounts.
+     */
+    total: string;
+  }
+
+  export namespace Data {
+    export interface PerPriceCost {
+      /**
+       * 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
+       * take a quantity and determine an amount to bill.
+       *
+       * Orb supports a few different pricing models out of the box. Each of these models
+       * is serialized differently in a given Price object. The model_type field
+       * determines the key for the configuration object that is present.
+       *
+       * ## Unit pricing
+       *
+       * With unit pricing, each unit costs a fixed amount.
+       *
+       * ```json
+       * {
+       *     ...
+       *     "model_type": "unit",
+       *     "unit_config": {
+       *         "unit_amount": "0.50"
+       *     }
+       *     ...
+       * }
+       * ```
+       *
+       * ## Tiered pricing
+       *
+       * In tiered pricing, the cost of a given unit depends on the tier range that it
+       * falls into, where each tier range is defined by an upper and lower bound. For
+       * example, the first ten units may cost $0.50 each and all units thereafter may
+       * cost $0.10 each.
+       *
+       * ```json
+       * {
+       *     ...
+       *     "model_type": "tiered",
+       *     "tiered_config": {
+       *         "tiers": [
+       *             {
+       *                 "first_unit": 1,
+       *                 "last_unit": 10,
+       *                 "unit_amount": "0.50"
+       *             },
+       *             {
+       *                 "first_unit": 11,
+       *                 "last_unit": null,
+       *                 "unit_amount": "0.10"
+       *             }
+       *         ]
+       *     }
+       *     ...
+       * ```
+       *
+       * ## Bulk pricing
+       *
+       * Bulk pricing applies when the number of units determine the cost of all units.
+       * For example, if you've bought less than 10 units, they may each be $0.50 for a
+       * total of $5.00. Once you've bought more than 10 units, all units may now be
+       * priced at $0.40 (i.e. 101 units total would be $40.40).
+       *
+       * ```json
+       * {
+       *     ...
+       *     "model_type": "bulk",
+       *     "bulk_config": {
+       *         "tiers": [
+       *             {
+       *                 "maximum_units": 10,
+       *                 "unit_amount": "0.50"
+       *             },
+       *             {
+       *                 "maximum_units": 1000,
+       *                 "unit_amount": "0.40"
+       *             }
+       *         ]
+       *     }
+       *     ...
+       * }
+       * ```
+       *
+       * ## Package pricing
+       *
+       * Package pricing defines the size or granularity of a unit for billing purposes.
+       * For example, if the package size is set to 5, then 4 units will be billed as 5
+       * and 6 units will be billed at 10.
+       *
+       * ```json
+       * {
+       *     ...
+       *     "model_type": "package",
+       *     "package_config": {
+       *         "package_amount": "0.80",
+       *         "package_size": 10
+       *     }
+       *     ...
+       * }
+       * ```
+       *
+       * ## BPS pricing
+       *
+       * BPS pricing specifies a per-event (e.g. per-payment) rate in one hundredth of a
+       * percent (the number of basis points to charge), as well as a cap per event to
+       * assess. For example, this would allow you to assess a fee of 0.25% on every
+       * payment you process, with a maximum charge of $25 per payment.
+       *
+       * ```json
+       * {
+       *     ...
+       *     "model_type": "bps",
+       *     "bps_config": {
+       *        "bps": 125,
+       *        "per_unit_maximum": "11.00"
+       *     }
+       *     ...
+       *  }
+       * ```
+       *
+       * ## Bulk BPS pricing
+       *
+       * Bulk BPS pricing specifies BPS parameters in a tiered manner, dependent on the
+       * total quantity across all events. Similar to bulk pricing, the BPS parameters of
+       * a given event depends on the tier range that the billing period falls into. Each
+       * tier range is defined by an upper bound. For example, after $1.5M of payment
+       * volume is reached, each individual payment may have a lower cap or a smaller
+       * take-rate.
+       *
+       * ```json
+       *     ...
+       *     "model_type": "bulk_bps",
+       *     "bulk_bps_config": {
+       *         "tiers": [
+       *            {
+       *                 "maximum_amount": "1000000.00",
+       *                 "bps": 125,
+       *                 "per_unit_maximum": "19.00"
+       *            },
+       *           {
+       *                 "maximum_amount": null,
+       *                 "bps": 115,
+       *                 "per_unit_maximum": "4.00"
+       *             }
+       *         ]
+       *     }
+       *     ...
+       * }
+       * ```
+       *
+       * ## Tiered BPS pricing
+       *
+       * Tiered BPS pricing specifies BPS parameters in a graduated manner, where an
+       * event's applicable parameter is a function of its marginal addition to the
+       * period total. Similar to tiered pricing, the BPS parameters of a given event
+       * depends on the tier range that it falls into, where each tier range is defined
+       * by an upper and lower bound. For example, the first few payments may have a 0.8
+       * BPS take-rate and all payments after a specific volume may incur a take-rate of
+       * 0.5 BPS each.
+       *
+       * ```json
+       *     ...
+       *     "model_type": "tiered_bps",
+       *     "tiered_bps_config": {
+       *         "tiers": [
+       *            {
+       *                 "minimum_amount": "0",
+       *                 "maximum_amount": "1000000.00",
+       *                 "bps": 125,
+       *                 "per_unit_maximum": "19.00"
+       *            },
+       *           {
+       *                 "minimum_amount": "1000000.00",
+       *                 "maximum_amount": null,
+       *                 "bps": 115,
+       *                 "per_unit_maximum": "4.00"
+       *             }
+       *         ]
+       *     }
+       *     ...
+       * }
+       * ```
+       *
+       * ## Matrix pricing
+       *
+       * Matrix pricing defines a set of unit prices in a one or two-dimensional matrix.
+       * `dimensions` defines the two event property values evaluated in this pricing
+       * model. In a one-dimensional matrix, the second value is `null`. Every
+       * configuration has a list of `matrix_values` which give the unit prices for
+       * specified property values. In a one-dimensional matrix, the matrix values will
+       * have `dimension_values` where the second value of the pair is null. If an event
+       * does not match any of the dimension values in the matrix, it will resort to the
+       * `default_unit_amount`.
+       *
+       * ```json
+       * {
+       *     "model_type": "matrix"
+       *     "matrix_config": {
+       *         "default_unit_amount": "3.00",
+       *         "dimensions": [
+       *             "cluster_name",
+       *             "region"
+       *         ],
+       *         "matrix_values": [
+       *             {
+       *                 "dimension_values": [
+       *                     "alpha",
+       *                     "west"
+       *                 ],
+       *                 "unit_amount": "2.00"
+       *             },
+       *             ...
+       *         ]
+       *     }
+       * }
+       * ```
+       *
+       * ### Fixed fees
+       *
+       * Fixed fees are prices that are applied independent of usage quantities, and
+       * follow unit pricing. They also have an additional parameter
+       * `fixed_price_quantity`. If the Price represents a fixed cost, this represents
+       * the quantity of units applied.
+       *
+       * ```json
+       * {
+       *     ...
+       *     "id": "price_id",
+       *     "model_type": "unit",
+       *     "unit_config": {
+       *        "unit_amount": "2.00"
+       *     },
+       *     "fixed_price_quantity": 3.0
+       *     ...
+       * }
+       * ```
+       */
+      price: PricesAPI.Price;
+
+      /**
+       * Price's contributions for the timeframe, excluding any minimums and discounts.
+       */
+      subtotal: string;
 
-export namespace CostListByExternalIDResponse {
-  export interface Data {
-    per_price_costs: Array<Data.PerPriceCost>;
+      /**
+       * Price's contributions for the timeframe, including minimums and discounts.
+       */
+      total: string;
 
-    /**
-     * Total costs for the timeframe, excluding any minimums and discounts.
-     */
-    subtotal: string;
+      /**
+       * If a `group_by` attribute is passed in, array of costs per `grouping_key`,
+       * `grouping_value` or `secondary_grouping_key`, `secondary_grouping_value`.
+       */
+      price_groups?: Array<PerPriceCost.PriceGroup> | null;
 
-    timeframe_end: string;
+      /**
+       * The price's quantity for the timeframe
+       */
+      quantity?: number | null;
+    }
 
-    timeframe_start: string;
+    export namespace PerPriceCost {
+      export interface PriceGroup {
+        /**
+         * Grouping key to break down a single price's costs
+         */
+        grouping_key: string;
 
-    /**
-     * Total costs for the timeframe, including any minimums and discounts.
-     */
-    total: string;
-  }
+        grouping_value: string | null;
 
-  export namespace Data {
-    export interface PerPriceCost {
+        /**
+         * If the price is a matrix price, this is the second dimension key
+         */
+        secondary_grouping_key: string | null;
+
+        secondary_grouping_value: string | null;
+
+        /**
+         * Total costs for this group for the timeframe. Note that this does not account
+         * for any minimums or discounts.
+         */
+        total: string;
+      }
+    }
+
+    export interface PerPriceCostV2 {
       /**
        * 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
@@ -902,7 +1466,7 @@ export namespace CostListByExternalIDResponse {
        * If a `group_by` attribute is passed in, array of costs per `grouping_key`,
        * `grouping_value` or `secondary_grouping_key`, `secondary_grouping_value`.
        */
-      price_groups?: Array<PerPriceCost.PriceGroup> | null;
+      price_groups?: Array<PerPriceCostV2.PriceGroup> | null;
 
       /**
        * The price's quantity for the timeframe
@@ -910,7 +1474,7 @@ export namespace CostListByExternalIDResponse {
       quantity?: number | null;
     }
 
-    export namespace PerPriceCost {
+    export namespace PerPriceCostV2 {
       export interface PriceGroup {
         /**
          * Grouping key to break down a single price's costs
@@ -937,11 +1501,6 @@ export namespace CostListByExternalIDResponse {
 }
 
 export interface CostListParams {
-  /**
-   * Groups per-price costs by the key provided.
-   */
-  group_by?: string | null;
-
   /**
    * Costs returned are exclusive of `timeframe_end`.
    */
@@ -962,11 +1521,6 @@ export interface CostListParams {
 }
 
 export interface CostListByExternalIDParams {
-  /**
-   * Groups per-price costs by the key provided.
-   */
-  group_by?: string | null;
-
   /**
    * Costs returned are exclusive of `timeframe_end`.
    */

package/src/resources/customers/credits/credits.ts

@@ -5,10 +5,12 @@ import { APIResource } from "../../../resource";
 import { isRequestOptions } from "../../../core";
 import * as CreditsAPI from "./credits";
 import * as LedgerAPI from "./ledger";
+import * as TopUpsAPI from "./top-ups";
 import { Page, type PageParams } from "../../../pagination";
 
 export class Credits extends APIResource {
   ledger: LedgerAPI.Ledger = new LedgerAPI.Ledger(this._client);
+  topUps: TopUpsAPI.TopUps = new TopUpsAPI.TopUps(this._client);
 
   /**
    * Returns a paginated list of unexpired, non-zero credit blocks for a customer.
@@ -120,4 +122,15 @@ export namespace Credits {
   export import LedgerCreateEntryParams = LedgerAPI.LedgerCreateEntryParams;
   export import LedgerCreateEntryByExternalIDParams = LedgerAPI.LedgerCreateEntryByExternalIDParams;
   export import LedgerListByExternalIDParams = LedgerAPI.LedgerListByExternalIDParams;
+  export import TopUps = TopUpsAPI.TopUps;
+  export import TopUpCreateResponse = TopUpsAPI.TopUpCreateResponse;
+  export import TopUpListResponse = TopUpsAPI.TopUpListResponse;
+  export import TopUpCreateByExternalIDResponse = TopUpsAPI.TopUpCreateByExternalIDResponse;
+  export import TopUpListByExternalIDResponse = TopUpsAPI.TopUpListByExternalIDResponse;
+  export import TopUpListResponsesPage = TopUpsAPI.TopUpListResponsesPage;
+  export import TopUpListByExternalIDResponsesPage = TopUpsAPI.TopUpListByExternalIDResponsesPage;
+  export import TopUpCreateParams = TopUpsAPI.TopUpCreateParams;
+  export import TopUpListParams = TopUpsAPI.TopUpListParams;
+  export import TopUpCreateByExternalIDParams = TopUpsAPI.TopUpCreateByExternalIDParams;
+  export import TopUpListByExternalIDParams = TopUpsAPI.TopUpListByExternalIDParams;
 }