orb-billing 1.21.0 → 1.22.0

package/resources/customers/costs.d.ts

@@ -0,0 +1,915 @@
+import * as Core from 'orb-billing/core';
+import { APIResource } from 'orb-billing/resource';
+import * as CostsAPI from 'orb-billing/resources/customers/costs';
+import * as PricesAPI from 'orb-billing/resources/prices/prices';
+export declare class Costs extends APIResource {
+    /**
+     * This endpoint is used to fetch a day-by-day snapshot of a customer's costs in
+     * Orb, calculated by applying pricing information to the underlying usage (see the
+     * [subscription usage endpoint](fetch-subscription-usage.api.mdx) to fetch usage
+     * per metric, in usage units rather than a currency).
+     *
+     * This endpoint can be leveraged for internal tooling and to provide a more
+     * transparent billing experience for your end users:
+     *
+     * 1. Understand the cost breakdown per line item historically and in real-time for
+     *    the current billing period.
+     * 2. Provide customer visibility into how different services are contributing to
+     *    the overall invoice with a per-day timeseries (as compared to the
+     *    [upcoming invoice](fetch-upcoming-invoice) resource, which represents a
+     *    snapshot for the current period).
+     * 3. Assess how minimums and discounts affect your customers by teasing apart
+     *    costs directly as a result of usage, as opposed to minimums and discounts at
+     *    the plan and price level.
+     * 4. Gain insight into key customer health metrics, such as the percent
+     *    utilization of the minimum committed spend.
+     *
+     * ## Fetching subscriptions
+     *
+     * By default, this endpoint fetches the currently active subscription for the
+     * customer, and returns cost information for the subscription's current billing
+     * period, broken down by each participating price. If there are no currently
+     * active subscriptions, this will instead default to the most recently active
+     * subscription or return an empty series if none are found. For example, if your
+     * plan charges for compute hours, job runs, and data syncs, then this endpoint
+     * would provide a daily breakdown of your customer's cost for each of those axes.
+     *
+     * If timeframe bounds are specified, Orb fetches all subscriptions that were
+     * active in that timeframe. If two subscriptions overlap on a single day, costs
+     * from each price will be summed, and prices for both subscriptions will be
+     * included in the breakdown.
+     *
+     * ## Prepaid plans
+     *
+     * For plans that include prices which deduct credits rather than accrue in-arrears
+     * charges in a billable currency, this endpoint will return the total deduction
+     * amount, in credits, for the specified timeframe.
+     *
+     * ## Cumulative subtotals and totals
+     *
+     * Since the subtotal and total must factor in any billing-period level discounts
+     * and minimums, it's most meaningful to consider costs relative to the start of
+     * the subscription's billing period. As a result, by default this endpoint returns
+     * cumulative totals since the beginning of the billing period. In particular, the
+     * `timeframe_start` of a returned timeframe window is _always_ the beginning of
+     * the billing period and `timeframe_end` is incremented one day at a time to build
+     * the result.
+     *
+     * A customer that uses a few API calls a day but has a minimum commitment might
+     * exhibit the following pattern for their subtotal and total in the first few days
+     * of the month. Here, we assume that each API call is $2.50, the customer's plan
+     * has a monthly minimum of $50 for this price, and that the subscription's billing
+     * period bounds are aligned to the first of the month:
+     *
+     * | timeframe_start | timeframe_end | Cumulative usage | Subtotal | Total (incl. commitment) |
+     * | --------------- | ------------- | ---------------- | -------- | ------------------------ |
+     * | 2023-02-01      | 2023-02-02    | 9                | $22.50   | $50.00                   |
+     * | 2023-02-01      | 2023-02-03    | 19               | $47.50   | $50.00                   |
+     * | 2023-02-01      | 2023-02-04    | 20               | $50.00   | $50.00                   |
+     * | 2023-02-01      | 2023-02-05    | 28               | $70.00   | $70.00                   |
+     * | 2023-02-01      | 2023-02-06    | 36               | $90.00   | $90.00                   |
+     *
+     * ### Periodic values
+     *
+     * When the query parameter `view_mode=periodic` is specified, Orb will return an
+     * incremental day-by-day view of costs. In this case, there will always be a
+     * one-day difference between `timeframe_start` and `timeframe_end` for the
+     * timeframes returned. This is a transform on top of the cumulative costs,
+     * calculated by taking the difference of each timeframe with the last. Note that
+     * in the above example, the `Total` value would be 0 for the second two data
+     * points, since the minimum commitment has not yet been hit and each day is not
+     * contributing anything to the total cost.
+     *
+     * ## Timeframe bounds
+     *
+     * If no timeframe bounds are specified, the response will default to the current
+     * billing period for the customer's subscription. For subscriptions that have
+     * ended, this will be the billing period when they were last active. If the
+     * subscription starts or ends within the timeframe, the response will only include
+     * windows where the subscription is active.
+     *
+     * As noted above, `timeframe_start` for a given cumulative datapoint is always the
+     * beginning of the billing period, and `timeframe_end` is incremented one day at a
+     * time to construct the response. When a timeframe is passed in that is not
+     * aligned to the current subscription's billing period, the response will contain
+     * cumulative totals from multiple billing periods.
+     *
+     * Suppose the queried customer has a subscription aligned to the 15th of every
+     * month. If this endpoint is queried with the date range `2023-06-01` -
+     * `2023-07-01`, the first data point will represent about half a billing period's
+     * worth of costs, accounting for accruals from the start of the billing period and
+     * inclusive of the first day of the timeframe
+     * (`timeframe_start = 2023-05-15 00:00:00`, `timeframe_end = 2023-06-02 00:00:00`)
+     *
+     * | datapoint index | timeframe_start | timeframe_end |
+     * | --------------- | --------------- | ------------- |
+     * | 0               | 2023-05-15      | 2023-06-02    |
+     * | 1               | 2023-05-15      | 2023-06-03    |
+     * | 2               | ...             | ...           |
+     * | 3               | 2023-05-15      | 2023-06-14    |
+     * | 4               | 2023-06-15      | 2023-06-16    |
+     * | 5               | 2023-06-15      | 2023-06-17    |
+     * | 6               | ...             | ...           |
+     * | 7               | 2023-06-15      | 2023-07-01    |
+     *
+     * You can see this sliced timeframe visualized
+     * [here](https://i.imgur.com/TXhYgme.png).
+     *
+     * ## Grouping by custom attributes
+     *
+     * In order to view costs grouped by a specific _attribute_ that each event is
+     * tagged with (i.e. `cluster`), you can additionally specify a `group_by` key. The
+     * `group_by` key denotes the event property on which to group.
+     *
+     * When returning grouped costs, a separate `price_group` object in the
+     * `per_price_costs` array is returned for each value of the `group_by` key present
+     * in your events. The `subtotal` value of the `per_price_costs` object is the sum
+     * of each `price_group`'s total.
+     *
+     * Orb expects events will contain values in the `properties` dictionary that
+     * correspond to the `group_by` key specified. By default, Orb will return a `null`
+     * group (i.e. events that match the metric but do not have the key set).
+     * Currently, it is only possible to view costs grouped by a single attribute at a
+     * time.
+     *
+     * ### Matrix prices
+     *
+     * When a price uses matrix pricing, it's important to view costs grouped by those
+     * matrix dimensions. Orb will return `price_groups` with the `grouping_key` and
+     * `secondary_grouping_key` based on the matrix price definition, for each
+     * `grouping_value` and `secondary_grouping_value` available.
+     */
+    list(customerId: string | null, query?: CostListParams, options?: Core.RequestOptions): Core.APIPromise<CostListResponse>;
+    list(customerId: string | null, options?: Core.RequestOptions): Core.APIPromise<CostListResponse>;
+    /**
+     * This endpoint is used to fetch a day-by-day snapshot of a customer's costs in
+     * Orb, calculated by applying pricing information to the underlying usage (see the
+     * [subscription usage endpoint](fetch-subscription-usage.api.mdx) to fetch usage
+     * per metric, in usage units rather than a currency).
+     *
+     * This endpoint can be leveraged for internal tooling and to provide a more
+     * transparent billing experience for your end users:
+     *
+     * 1. Understand the cost breakdown per line item historically and in real-time for
+     *    the current billing period.
+     * 2. Provide customer visibility into how different services are contributing to
+     *    the overall invoice with a per-day timeseries (as compared to the
+     *    [upcoming invoice](fetch-upcoming-invoice) resource, which represents a
+     *    snapshot for the current period).
+     * 3. Assess how minimums and discounts affect your customers by teasing apart
+     *    costs directly as a result of usage, as opposed to minimums and discounts at
+     *    the plan and price level.
+     * 4. Gain insight into key customer health metrics, such as the percent
+     *    utilization of the minimum committed spend.
+     *
+     * ## Fetching subscriptions
+     *
+     * By default, this endpoint fetches the currently active subscription for the
+     * customer, and returns cost information for the subscription's current billing
+     * period, broken down by each participating price. If there are no currently
+     * active subscriptions, this will instead default to the most recently active
+     * subscription or return an empty series if none are found. For example, if your
+     * plan charges for compute hours, job runs, and data syncs, then this endpoint
+     * would provide a daily breakdown of your customer's cost for each of those axes.
+     *
+     * If timeframe bounds are specified, Orb fetches all subscriptions that were
+     * active in that timeframe. If two subscriptions overlap on a single day, costs
+     * from each price will be summed, and prices for both subscriptions will be
+     * included in the breakdown.
+     *
+     * ## Prepaid plans
+     *
+     * For plans that include prices which deduct credits rather than accrue in-arrears
+     * charges in a billable currency, this endpoint will return the total deduction
+     * amount, in credits, for the specified timeframe.
+     *
+     * ## Cumulative subtotals and totals
+     *
+     * Since the subtotal and total must factor in any billing-period level discounts
+     * and minimums, it's most meaningful to consider costs relative to the start of
+     * the subscription's billing period. As a result, by default this endpoint returns
+     * cumulative totals since the beginning of the billing period. In particular, the
+     * `timeframe_start` of a returned timeframe window is _always_ the beginning of
+     * the billing period and `timeframe_end` is incremented one day at a time to build
+     * the result.
+     *
+     * A customer that uses a few API calls a day but has a minimum commitment might
+     * exhibit the following pattern for their subtotal and total in the first few days
+     * of the month. Here, we assume that each API call is $2.50, the customer's plan
+     * has a monthly minimum of $50 for this price, and that the subscription's billing
+     * period bounds are aligned to the first of the month:
+     *
+     * | timeframe_start | timeframe_end | Cumulative usage | Subtotal | Total (incl. commitment) |
+     * | --------------- | ------------- | ---------------- | -------- | ------------------------ |
+     * | 2023-02-01      | 2023-02-02    | 9                | $22.50   | $50.00                   |
+     * | 2023-02-01      | 2023-02-03    | 19               | $47.50   | $50.00                   |
+     * | 2023-02-01      | 2023-02-04    | 20               | $50.00   | $50.00                   |
+     * | 2023-02-01      | 2023-02-05    | 28               | $70.00   | $70.00                   |
+     * | 2023-02-01      | 2023-02-06    | 36               | $90.00   | $90.00                   |
+     *
+     * ### Periodic values
+     *
+     * When the query parameter `view_mode=periodic` is specified, Orb will return an
+     * incremental day-by-day view of costs. In this case, there will always be a
+     * one-day difference between `timeframe_start` and `timeframe_end` for the
+     * timeframes returned. This is a transform on top of the cumulative costs,
+     * calculated by taking the difference of each timeframe with the last. Note that
+     * in the above example, the `Total` value would be 0 for the second two data
+     * points, since the minimum commitment has not yet been hit and each day is not
+     * contributing anything to the total cost.
+     *
+     * ## Timeframe bounds
+     *
+     * If no timeframe bounds are specified, the response will default to the current
+     * billing period for the customer's subscription. For subscriptions that have
+     * ended, this will be the billing period when they were last active. If the
+     * subscription starts or ends within the timeframe, the response will only include
+     * windows where the subscription is active.
+     *
+     * As noted above, `timeframe_start` for a given cumulative datapoint is always the
+     * beginning of the billing period, and `timeframe_end` is incremented one day at a
+     * time to construct the response. When a timeframe is passed in that is not
+     * aligned to the current subscription's billing period, the response will contain
+     * cumulative totals from multiple billing periods.
+     *
+     * Suppose the queried customer has a subscription aligned to the 15th of every
+     * month. If this endpoint is queried with the date range `2023-06-01` -
+     * `2023-07-01`, the first data point will represent about half a billing period's
+     * worth of costs, accounting for accruals from the start of the billing period and
+     * inclusive of the first day of the timeframe
+     * (`timeframe_start = 2023-05-15 00:00:00`, `timeframe_end = 2023-06-02 00:00:00`)
+     *
+     * | datapoint index | timeframe_start | timeframe_end |
+     * | --------------- | --------------- | ------------- |
+     * | 0               | 2023-05-15      | 2023-06-02    |
+     * | 1               | 2023-05-15      | 2023-06-03    |
+     * | 2               | ...             | ...           |
+     * | 3               | 2023-05-15      | 2023-06-14    |
+     * | 4               | 2023-06-15      | 2023-06-16    |
+     * | 5               | 2023-06-15      | 2023-06-17    |
+     * | 6               | ...             | ...           |
+     * | 7               | 2023-06-15      | 2023-07-01    |
+     *
+     * You can see this sliced timeframe visualized
+     * [here](https://i.imgur.com/TXhYgme.png).
+     *
+     * ## Grouping by custom attributes
+     *
+     * In order to view costs grouped by a specific _attribute_ that each event is
+     * tagged with (i.e. `cluster`), you can additionally specify a `group_by` key. The
+     * `group_by` key denotes the event property on which to group.
+     *
+     * When returning grouped costs, a separate `price_group` object in the
+     * `per_price_costs` array is returned for each value of the `group_by` key present
+     * in your events. The `subtotal` value of the `per_price_costs` object is the sum
+     * of each `price_group`'s total.
+     *
+     * Orb expects events will contain values in the `properties` dictionary that
+     * correspond to the `group_by` key specified. By default, Orb will return a `null`
+     * group (i.e. events that match the metric but do not have the key set).
+     * Currently, it is only possible to view costs grouped by a single attribute at a
+     * time.
+     *
+     * ### Matrix prices
+     *
+     * When a price uses matrix pricing, it's important to view costs grouped by those
+     * matrix dimensions. Orb will return `price_groups` with the `grouping_key` and
+     * `secondary_grouping_key` based on the matrix price definition, for each
+     * `grouping_value` and `secondary_grouping_value` available.
+     */
+    listByExternalId(externalCustomerId: string | null, query?: CostListByExternalIDParams, options?: Core.RequestOptions): Core.APIPromise<CostListByExternalIDResponse>;
+    listByExternalId(externalCustomerId: string | null, options?: Core.RequestOptions): Core.APIPromise<CostListByExternalIDResponse>;
+}
+export interface CostListResponse {
+    data: Array<CostListResponse.Data>;
+}
+export declare namespace CostListResponse {
+    interface Data {
+        per_price_costs: Array<Data.PerPriceCost>;
+        /**
+         * 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;
+    }
+    namespace Data {
+        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;
+            /**
+             * 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<PerPriceCost.PriceGroup> | null;
+            /**
+             * The price's quantity for the timeframe
+             */
+            quantity?: number | null;
+        }
+        namespace PerPriceCost {
+            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 declare namespace CostListByExternalIDResponse {
+    interface Data {
+        per_price_costs: Array<Data.PerPriceCost>;
+        /**
+         * 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;
+    }
+    namespace Data {
+        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;
+            /**
+             * 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<PerPriceCost.PriceGroup> | null;
+            /**
+             * The price's quantity for the timeframe
+             */
+            quantity?: number | null;
+        }
+        namespace PerPriceCost {
+            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 CostListParams {
+    /**
+     * Groups per-price costs by the key provided.
+     */
+    group_by?: string | null;
+    /**
+     * Costs returned are exclusive of `timeframe_end`.
+     */
+    timeframe_end?: string | null;
+    /**
+     * Costs returned are inclusive of `timeframe_start`.
+     */
+    timeframe_start?: string | null;
+    /**
+     * Controls whether Orb returns cumulative costs since the start of the billing
+     * period, or incremental day-by-day costs. If your customer has minimums or
+     * discounts, it's strongly recommended that you use the default cumulative
+     * behavior.
+     */
+    view_mode?: 'periodic' | 'cumulative' | null;
+}
+export interface CostListByExternalIDParams {
+    /**
+     * Groups per-price costs by the key provided.
+     */
+    group_by?: string | null;
+    /**
+     * Costs returned are exclusive of `timeframe_end`.
+     */
+    timeframe_end?: string | null;
+    /**
+     * Costs returned are inclusive of `timeframe_start`.
+     */
+    timeframe_start?: string | null;
+    /**
+     * Controls whether Orb returns cumulative costs since the start of the billing
+     * period, or incremental day-by-day costs. If your customer has minimums or
+     * discounts, it's strongly recommended that you use the default cumulative
+     * behavior.
+     */
+    view_mode?: 'periodic' | 'cumulative' | null;
+}
+export declare namespace Costs {
+    export import CostListResponse = CostsAPI.CostListResponse;
+    export import CostListByExternalIDResponse = CostsAPI.CostListByExternalIDResponse;
+    export import CostListParams = CostsAPI.CostListParams;
+    export import CostListByExternalIDParams = CostsAPI.CostListByExternalIDParams;
+}
+//# sourceMappingURL=costs.d.ts.map