orb-billing
Version:
The official TypeScript library for the Orb API
205 lines • 8.92 kB
JavaScript
;
// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
Object.defineProperty(exports, "__esModule", { value: true });
exports.Prices = void 0;
const tslib_1 = require("../../internal/tslib.js");
const resource_1 = require("../../core/resource.js");
const ExternalPriceIDAPI = tslib_1.__importStar(require("./external-price-id.js"));
const external_price_id_1 = require("./external-price-id.js");
const pagination_1 = require("../../core/pagination.js");
const path_1 = require("../../internal/utils/path.js");
/**
* 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.
*
* For more on the types of prices, see [the core concepts documentation](/core-concepts#plan-and-price)
*/
class Prices extends resource_1.APIResource {
constructor() {
super(...arguments);
this.externalPriceID = new ExternalPriceIDAPI.ExternalPriceID(this._client);
}
/**
* This endpoint is used to create a [price](/product-catalog/price-configuration).
* A price created using this endpoint is always an add-on, meaning that it's not
* associated with a specific plan and can instead be individually added to
* subscriptions, including subscriptions on different plans.
*
* An `external_price_id` can be optionally specified as an alias to allow
* ergonomic interaction with prices in the Orb API.
*
* See the [Price resource](/product-catalog/price-configuration) for the
* specification of different price model configurations possible in this endpoint.
*
* @example
* ```ts
* const price = await client.prices.create({
* cadence: 'annual',
* currency: 'currency',
* item_id: 'item_id',
* model_type: 'unit',
* name: 'Annual fee',
* unit_config: { unit_amount: 'unit_amount' },
* });
* ```
*/
create(body, options) {
return this._client.post('/prices', { body, ...options });
}
/**
* This endpoint allows you to update the `metadata` property on a price. If you
* pass null for the metadata value, it will clear any existing metadata for that
* price.
*
* @example
* ```ts
* const price = await client.prices.update('price_id');
* ```
*/
update(priceID, body, options) {
return this._client.put((0, path_1.path) `/prices/${priceID}`, { body, ...options });
}
/**
* This endpoint is used to list all add-on prices created using the
* [price creation endpoint](/api-reference/price/create-price).
*
* @example
* ```ts
* // Automatically fetches more pages as needed.
* for await (const price of client.prices.list()) {
* // ...
* }
* ```
*/
list(query = {}, options) {
return this._client.getAPIList('/prices', (pagination_1.Page), { query, ...options });
}
/**
* [NOTE] It is recommended to use the `/v1/prices/evaluate` which offers further
* functionality, such as multiple prices, inline price definitions, and querying
* over preview events.
*
* 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](/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.
*
* @example
* ```ts
* const response = await client.prices.evaluate('price_id', {
* timeframe_end: '2019-12-27T18:11:19.117Z',
* timeframe_start: '2019-12-27T18:11:19.117Z',
* });
* ```
*/
evaluate(priceID, body, options) {
return this._client.post((0, path_1.path) `/prices/${priceID}/evaluate`, { body, ...options });
}
/**
* This endpoint is used to evaluate the output of price(s) for a given customer
* and time range over ingested events. It enables filtering and grouping the
* output using
* [computed properties](/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'`.
*
* Prices may either reference existing prices in your Orb account or be defined
* inline in the request body. Up to 100 prices can be evaluated in a single
* request.
*
* Prices are evaluated on ingested events and the start of the time range must be
* no more than 100 days ago. To evaluate based off a set of provided events, the
* [evaluate preview events](/api-reference/price/evaluate-preview-events) endpoint
* can be used instead.
*
* Note that this is a POST endpoint rather than a GET endpoint because it employs
* a JSON body rather than query parameters.
*
* @example
* ```ts
* const response = await client.prices.evaluateMultiple({
* timeframe_end: '2019-12-27T18:11:19.117Z',
* timeframe_start: '2019-12-27T18:11:19.117Z',
* });
* ```
*/
evaluateMultiple(body, options) {
return this._client.post('/prices/evaluate', { body, ...options });
}
/**
* This endpoint evaluates prices on preview events instead of actual usage, making
* it ideal for building price calculators and cost estimation tools. You can
* filter and group results using
* [computed properties](/extensibility/advanced-metrics#computed-properties) to
* analyze pricing across different dimensions.
*
* Prices may either reference existing prices in your Orb account or be defined
* inline in the request body. The endpoint has the following limitations:
*
* 1. Up to 100 prices can be evaluated in a single request.
* 2. Up to 500 preview events can be provided in a single request.
*
* A top-level customer_id is required to evaluate the preview events.
* Additionally, all events without a customer_id will have the top-level
* customer_id added.
*
* Note that this is a POST endpoint rather than a GET endpoint because it employs
* a JSON body rather than query parameters.
*
* @example
* ```ts
* const response = await client.prices.evaluatePreviewEvents({
* timeframe_end: '2019-12-27T18:11:19.117Z',
* timeframe_start: '2019-12-27T18:11:19.117Z',
* });
* ```
*/
evaluatePreviewEvents(body, options) {
return this._client.post('/prices/evaluate_preview_events', { body, ...options });
}
/**
* This endpoint returns a price given an identifier.
*
* @example
* ```ts
* const price = await client.prices.fetch('price_id');
* ```
*/
fetch(priceID, options) {
return this._client.get((0, path_1.path) `/prices/${priceID}`, options);
}
}
exports.Prices = Prices;
Prices.ExternalPriceID = external_price_id_1.ExternalPriceID;
//# sourceMappingURL=prices.js.map