orb-billing
Version:
The official TypeScript library for the Orb API
293 lines • 17.5 kB
JavaScript
;
// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
Object.defineProperty(exports, "__esModule", { value: true });
exports.Costs = void 0;
const resource_1 = require("../../core/resource.js");
const path_1 = require("../../internal/utils/path.js");
/**
* A customer is a buyer of your products, and the other party to the billing relationship.
*
* In Orb, customers are assigned system generated identifiers automatically, but it's often desirable to have these
* match existing identifiers in your system. To avoid having to denormalize Orb ID information, you can pass in an
* `external_customer_id` with your own identifier. See
* [Customer ID Aliases](/events-and-metrics/customer-aliases) for further information about how these
* aliases work in Orb.
*
* In addition to having an identifier in your system, a customer may exist in a payment provider solution like
* Stripe. Use the `payment_provider_id` and the `payment_provider` enum field to express this mapping.
*
* A customer also has a timezone (from the standard [IANA timezone database](https://www.iana.org/time-zones)), which
* defaults to your account's timezone. See [Timezone localization](/essentials/timezones) for
* information on what this timezone parameter influences within Orb.
*/
class Costs extends resource_1.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](/api-reference/subscription/fetch-subscription-usage)
* 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](/api-reference/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
*
* For an active subscription, both timeframes should be specified in the request.
* If a subscription starts or ends within the timeframe, the response will only
* include windows where the subscription is active. If a subscription has ended,
* no timeframe bounds need to be specified and the response will default to the
* billing period when the subscription was last 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).
*
* ### 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.
*
* ## Trials
*
* During a trial, usage prices carry a trial discount, capped at the plan's trial
* maximum amount (or 100% when no maximum is set), and the trial period is billed
* as a single invoice dated at the trial's end. In the costs response,
* trial-period usage appears at full list price in `subtotal`, with the trial
* discount reflected in `total`: `total` is \$0 as long as usage stays within the
* trial maximum, and usage beyond the maximum bills normally. Fixed fees are not
* charged during a trial.
*/
list(customerID, query = {}, options) {
return this._client.get((0, path_1.path) `/customers/${customerID}/costs`, { query, ...options });
}
/**
* 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](/api-reference/subscription/fetch-subscription-usage)
* 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](/api-reference/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
*
* For an active subscription, both timeframes should be specified in the request.
* If a subscription starts or ends within the timeframe, the response will only
* include windows where the subscription is active. If a subscription has ended,
* no timeframe bounds need to be specified and the response will default to the
* billing period when the subscription was last 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).
*
* ### 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.
*
* ## Trials
*
* During a trial, usage prices carry a trial discount, capped at the plan's trial
* maximum amount (or 100% when no maximum is set), and the trial period is billed
* as a single invoice dated at the trial's end. In the costs response,
* trial-period usage appears at full list price in `subtotal`, with the trial
* discount reflected in `total`: `total` is \$0 as long as usage stays within the
* trial maximum, and usage beyond the maximum bills normally. Fixed fees are not
* charged during a trial.
*/
listByExternalID(externalCustomerID, query = {}, options) {
return this._client.get((0, path_1.path) `/customers/external_customer_id/${externalCustomerID}/costs`, {
query,
...options,
});
}
}
exports.Costs = Costs;
//# sourceMappingURL=costs.js.map