orb-billing 1.21.0 → 1.22.0

package/docs/sdks/customer/README.md

@@ -1,1080 +0,0 @@
-# Customer
-(*customer*)
-
-## Overview
-
-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](../guides/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](../guides/product-catalog/timezones.md) for
-information on what this timezone parameter influences within Orb.
-
-### Available Operations
-
-* [amend](#amend) - Amend usage
-* [amendByExternalId](#amendbyexternalid) - Amend usage by external ID
-* [create](#create) - Create customer
-* [createBalanceTransaction](#createbalancetransaction) - Create customer balance transaction
-* [delete](#delete) - Delete customer
-* [fetch](#fetch) - Fetch customer
-* [fetchByExternalId](#fetchbyexternalid) - Fetch customer by external ID
-* [fetchCosts](#fetchcosts) - Fetch customer costs
-* [fetchCostsByExternalId](#fetchcostsbyexternalid) - Fetch customer costs by external ID
-* [list](#list) - List customers
-* [listBalanceTransactions](#listbalancetransactions) - List balance transactions
-* [updateByExternalId](#updatebyexternalid) - Update customer by external ID
-* [updateCustomer](#updatecustomer) - Update customer
-
-## amend
-
-This endpoint is used to amend usage within a timeframe for a customer that has an active subscription.
-
-This endpoint will mark _all_ existing events within `[timeframe_start, timeframe_end)` as _ignored_  for billing  purpo
-ses, and Orb will only use the _new_ events passed in the body of this request as the source of truth for that timeframe
-moving forwards.
-Note that a given time period can be amended any number of times, so events can be overwritten in subsequent calls to th
-is endpoint.
-
-This is a powerful and audit-safe mechanism to retroactively change usage data in cases where you need to:
-- decrease historical usage consumption because of degraded service availability in your systems
-- account for gaps from your usage reporting mechanism
-- make point-in-time fixes for specific event records, while ret
-aining the original time of usage and associated metadata.
-This amendment API is designed with two explicit goals:
-1. Amendments are **always audit-safe**. The amendment process
-will still retain original events in the timeframe, though they will be ignored for billing calculations. For auditing a
-nd data fidelity purposes, Orb never overwrites or permanently deletes ingested usage data.
-2. Amendments always preser
-ve data **consistency**. In other words, either an amendment is fully processed by the system (and the new events for th
-e timeframe are honored rather than the existing ones) or the amendment request fails. To maintain this important proper
-ty, Orb prevents _partial event ingestion_ on this endpoint.
-
-## Response semantics
-- Either all events are ingested successfully, or all fail to ingest (returning a `4xx` or `5xx` response code).
-- Any event that fails schema validation will lead to a `4xx` response. In this case, to maintain data consistency,
-Orb will not ingest any events and will
-also not deprecate existing events in the time period.
-- You can assume that the amendment is successful on receipt of
-a `2xx` response.While a successful response from this endpoint indicates that the new events have been ingested, updati
-ng usage totals happens asynchronously and may be delayed by a few minutes.
-
-As emphasized above, Orb will never show
-an inconsistent state (e.g. in invoice previews or dashboards); either it will show the existing state (before the amend
-ment) or the new state (with new events in the requested timeframe).
-
-## Sample request body
-```json
-{
-    "events": [{
-        "event_name": "payment_processed",
-        "timestamp": "2022-03-24T07:15:00Z",
-        "properties": {
-            "amount": 100
-        }
-    }, {
-        "event_name": "payment_failed",
-        "timestamp": "2022-03-24T07:15:00Z",
-        "properties": {
-                "amount": 100
-        }
-    }]
-}
-```
-
-## Request Validation
-- The `timestamp` of
-each event reported must fall within the bounds of `timeframe_start` and `timeframe_end`. As with ingestion, all timesta
-mps must be sent in ISO8601 format with UTC timezone offset.
-- Orb **does not accept an `idempotency_key`** with each
-event in this endpoint, since the entirety of the event list must be ingested to ensure consistency. On retryable errors
-, you should retry the request in its entirety, and assume that the amendment operation has not succeeded until receipt
-of a `2xx`.
-
-- Both `timeframe_start` and `timeframe_end` must be timestamps in the past. Furthermore, Orb will genera
-lly validate that the `timeframe_start` and `timeframe_end` fall within the customer's _current_ subscription billing pe
-riod. However, Orb does allow amendments while in the grace period of the previous billing period; in this instance, the
-timeframe can start before the current period.
-
-## API Limits
-Note that Orb does not currently enforce a hard rate-
-limit for API usage or a maximum request payload size. Similar to the event ingestion API, this API is architected for h
-igh-throughput ingestion. It is also safe to _programmatically_ call this endpoint if your system can automatically dete
-ct a need for historical amendment.
-
-In order to overwrite timeframes with a very large number of events, we suggest using multiple calls with small adjacent
-(e.g. every hour) timeframes.
-
-### Example Usage
-
-```typescript
-import { Orb } from "orb-billing";
-import { AmendUsageRequest } from "orb-billing/dist/sdk/models/operations";
-import { UpdateEvent, UpdateEventProperties } from "orb-billing/dist/sdk/models/shared";
-
-(async() => {
-  const sdk = new Orb({
-    security: {
-      apiKey: "",
-    },
-  });
-const customerId: string = "Steel";
-const updateEvent: UpdateEvent = {
-  eventName: "channels",
-  properties: {},
-  timestamp: new Date("2020-12-09T16:09:53Z"),
-};
-const timeframeEnd: Date = new Date("2022-10-24T01:13:02.226Z");
-const timeframeStart: Date = new Date("2022-08-07T07:39:12.946Z");
-
-  const res = await sdk.customer.amend(customerId, updateEvent, timeframeEnd, timeframeStart);
-
-  if (res.statusCode == 200) {
-    // handle response
-  }
-})();
-```
-
-### Parameters
-
-| Parameter                                                                                     | Type                                                                                          | Required                                                                                      | Description                                                                                   |
-| --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
-| `customerId`                                                                                  | *string*                                                                                      | :heavy_check_mark:                                                                            | N/A                                                                                           |
-| `updateEvent`                                                                                 | [shared.UpdateEvent](../../models/shared/updateevent.md)                                      | :heavy_minus_sign:                                                                            | N/A                                                                                           |
-| `timeframeEnd`                                                                                | [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) | :heavy_minus_sign:                                                                            | N/A                                                                                           |
-| `timeframeStart`                                                                              | [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) | :heavy_minus_sign:                                                                            | N/A                                                                                           |
-| `config`                                                                                      | [AxiosRequestConfig](https://axios-http.com/docs/req_config)                                  | :heavy_minus_sign:                                                                            | Available config options for making requests.                                                 |
-
-
-### Response
-
-**Promise<[operations.AmendUsageResponse](../../models/operations/amendusageresponse.md)>**
-
-
-## amendByExternalId
-
-This endpoint is used to amend usage within a timeframe for a customer that has an active subscription.
-
-This endpoint will mark _all_ existing events within `[timeframe_start, timeframe_end)` as _ignored_  for billing  purpo
-ses, and Orb will only use the _new_ events passed in the body of this request as the source of truth for that timeframe
-moving forwards.
-Note that a given time period can be amended any number of times, so events can be overwritten in subsequent calls to th
-is endpoint.
-
-This is a powerful and audit-safe mechanism to retroactively change usage data in cases where you need to:
-- decrease historical usage consumption because of degraded service availability in your systems
-- account for gaps from your usage reporting mechanism
-- make point-in-time fixes for specific event records, while ret
-aining the original time of usage and associated metadata.
-This amendment API is designed with two explicit goals:
-1. Amendments are **always audit-safe**. The amendment process
-will still retain original events in the timeframe, though they will be ignored for billing calculations. For auditing a
-nd data fidelity purposes, Orb never overwrites or permanently deletes ingested usage data.
-2. Amendments always preser
-ve data **consistency**. In other words, either an amendment is fully processed by the system (and the new events for th
-e timeframe are honored rather than the existing ones) or the amendment request fails. To maintain this important proper
-ty, Orb prevents _partial event ingestion_ on this endpoint.
-
-## Response semantics
-- Either all events are ingested successfully, or all fail to ingest (returning a `4xx` or `5xx` response code).
-- Any event that fails schema validation will lead to a `4xx` response. In this case, to maintain data consistency,
-Orb will not ingest any events and will
-also not deprecate existing events in the time period.
-- You can assume that the amendment is successful on receipt of
-a `2xx` response.While a successful response from this endpoint indicates that the new events have been ingested, updati
-ng usage totals happens asynchronously and may be delayed by a few minutes.
-
-As emphasized above, Orb will never show
-an inconsistent state (e.g. in invoice previews or dashboards); either it will show the existing state (before the amend
-ment) or the new state (with new events in the requested timeframe).
-
-## Sample request body
-```json
-{
-    "events": [{
-        "event_name": "payment_processed",
-        "timestamp": "2022-03-24T07:15:00Z",
-        "properties": {
-            "amount": 100
-        }
-    }, {
-        "event_name": "payment_failed",
-        "timestamp": "2022-03-24T07:15:00Z",
-        "properties": {
-                "amount": 100
-        }
-    }]
-}
-```
-
-## Request Validation
-- The `timestamp` of
-each event reported must fall within the bounds of `timeframe_start` and `timeframe_end`. As with ingestion, all timesta
-mps must be sent in ISO8601 format with UTC timezone offset.
-- Orb **does not accept an `idempotency_key`** with each
-event in this endpoint, since the entirety of the event list must be ingested to ensure consistency. On retryable errors
-, you should retry the request in its entirety, and assume that the amendment operation has not succeeded until receipt
-of a `2xx`.
-
-- Both `timeframe_start` and `timeframe_end` must be timestamps in the past. Furthermore, Orb will genera
-lly validate that the `timeframe_start` and `timeframe_end` fall within the customer's _current_ subscription billing pe
-riod. However, Orb does allow amendments while in the grace period of the previous billing period; in this instance, the
-timeframe can start before the current period.
-
-## API Limits
-Note that Orb does not currently enforce a hard rate-
-limit for API usage or a maximum request payload size. Similar to the event ingestion API, this API is architected for h
-igh-throughput ingestion. It is also safe to _programmatically_ call this endpoint if your system can automatically dete
-ct a need for historical amendment.
-
-In order to overwrite timeframes with a very large number of events, we suggest using multiple calls with small adjacent
-(e.g. every hour) timeframes.
-
-### Example Usage
-
-```typescript
-import { Orb } from "orb-billing";
-import { AmendUsageExternalCustomerIdRequest } from "orb-billing/dist/sdk/models/operations";
-import { UpdateEvent, UpdateEventProperties } from "orb-billing/dist/sdk/models/shared";
-
-(async() => {
-  const sdk = new Orb({
-    security: {
-      apiKey: "",
-    },
-  });
-const externalCustomerId: string = "Awesome";
-const updateEvent: UpdateEvent = {
-  eventName: "Assurance Highway Gloves",
-  properties: {},
-  timestamp: new Date("2020-12-09T16:09:53Z"),
-};
-const timeframeEnd: Date = new Date("2022-11-04T12:23:37.450Z");
-const timeframeStart: Date = new Date("2021-02-05T19:10:39.767Z");
-
-  const res = await sdk.customer.amendByExternalId(externalCustomerId, updateEvent, timeframeEnd, timeframeStart);
-
-  if (res.statusCode == 200) {
-    // handle response
-  }
-})();
-```
-
-### Parameters
-
-| Parameter                                                                                     | Type                                                                                          | Required                                                                                      | Description                                                                                   |
-| --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
-| `externalCustomerId`                                                                          | *string*                                                                                      | :heavy_check_mark:                                                                            | N/A                                                                                           |
-| `updateEvent`                                                                                 | [shared.UpdateEvent](../../models/shared/updateevent.md)                                      | :heavy_minus_sign:                                                                            | N/A                                                                                           |
-| `timeframeEnd`                                                                                | [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) | :heavy_minus_sign:                                                                            | N/A                                                                                           |
-| `timeframeStart`                                                                              | [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) | :heavy_minus_sign:                                                                            | N/A                                                                                           |
-| `config`                                                                                      | [AxiosRequestConfig](https://axios-http.com/docs/req_config)                                  | :heavy_minus_sign:                                                                            | Available config options for making requests.                                                 |
-
-
-### Response
-
-**Promise<[operations.AmendUsageExternalCustomerIdResponse](../../models/operations/amendusageexternalcustomeridresponse.md)>**
-
-
-## create
-
-This operation is used to create an Orb customer, who is party to the core billing relationship. See
-[Customer](../guides/concepts#customer) for an overview of the customer resource.
-
-This endpoint is critical in the following Orb functionality:
-* Automated charges can be configured by setting `payment_provider` and `payment_provider_id` to automatically
-  issue invoices
-* [Customer ID Aliases](../guides/events-and-metrics/customer-aliases) can be configured by setting
-  `external_customer_id`
-* [Timezone localization](../guides/product-catalog/timezones.md) can be configured on a per-customer basis by
-  setting the `timezone` parameter
-
-### Example Usage
-
-```typescript
-import { Orb } from "orb-billing";
-import { NewCustomerPaymentProvider } from "orb-billing/dist/sdk/models/shared";
-
-(async() => {
-  const sdk = new Orb({
-    security: {
-      apiKey: "",
-    },
-  });
-
-  const res = await sdk.customer.create({
-    accountingSyncConfiguration: {
-      accountingProviders: [
-        {
-          externalProviderId: "bluetooth Extended",
-          providerType: "blue",
-        },
-      ],
-    },
-    additionalEmails: [
-      "shred",
-    ],
-    billingAddress: {},
-    email: "Valerie45@yahoo.com",
-    metadata: {},
-    name: "evolve",
-    reportingConfiguration: {
-      exempt: false,
-    },
-    shippingAddress: {},
-    taxId: {
-      country: "Portugal",
-      type: "SUV quantify Polestar",
-      value: "physical Ameliorated",
-    },
-  });
-
-  if (res.statusCode == 200) {
-    // handle response
-  }
-})();
-```
-
-### Parameters
-
-| Parameter                                                    | Type                                                         | Required                                                     | Description                                                  |
-| ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
-| `request`                                                    | [shared.NewCustomer](../../models/shared/newcustomer.md)     | :heavy_check_mark:                                           | The request object to use for the request.                   |
-| `config`                                                     | [AxiosRequestConfig](https://axios-http.com/docs/req_config) | :heavy_minus_sign:                                           | Available config options for making requests.                |
-
-
-### Response
-
-**Promise<[operations.CreateCustomerResponse](../../models/operations/createcustomerresponse.md)>**
-
-
-## createBalanceTransaction
-
-Creates an immutable balance transaction that updates the customer's balance and returns back the newly created
-transaction.
-
-### Example Usage
-
-```typescript
-import { Orb } from "orb-billing";
-import { CreateCustomerBalanceTransactionRequest } from "orb-billing/dist/sdk/models/operations";
-import { NewCustomerBalanceTransaction, NewCustomerBalanceTransactionType } from "orb-billing/dist/sdk/models/shared";
-
-(async() => {
-  const sdk = new Orb({
-    security: {
-      apiKey: "",
-    },
-  });
-const customerId: string = "Intelligent";
-const newCustomerBalanceTransaction: NewCustomerBalanceTransaction = {
-  amount: "233.83",
-  type: NewCustomerBalanceTransactionType.Decrement,
-};
-
-  const res = await sdk.customer.createBalanceTransaction(customerId, newCustomerBalanceTransaction);
-
-  if (res.statusCode == 200) {
-    // handle response
-  }
-})();
-```
-
-### Parameters
-
-| Parameter                                                                                    | Type                                                                                         | Required                                                                                     | Description                                                                                  |
-| -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
-| `customerId`                                                                                 | *string*                                                                                     | :heavy_check_mark:                                                                           | N/A                                                                                          |
-| `newCustomerBalanceTransaction`                                                              | [shared.NewCustomerBalanceTransaction](../../models/shared/newcustomerbalancetransaction.md) | :heavy_minus_sign:                                                                           | N/A                                                                                          |
-| `config`                                                                                     | [AxiosRequestConfig](https://axios-http.com/docs/req_config)                                 | :heavy_minus_sign:                                                                           | Available config options for making requests.                                                |
-
-
-### Response
-
-**Promise<[operations.CreateCustomerBalanceTransactionResponse](../../models/operations/createcustomerbalancetransactionresponse.md)>**
-
-
-## delete
-
-This performs a deletion of this customer, its subscriptions, and its invoices.
-This operation is irreversible. Note that this is a _soft_ deletion, but the data
-will be inaccessible through the API and Orb dashboard. For hard-deletion, please
-reach out to the Orb team directly.
-
-**Note**: This operation happens asynchronously and can be expected to take a
-few minutes to propagate to related resources. However, querying for the customer on
-subsequent GET requests while deletion is in process will reflect its deletion with
-a `deleted: true` property. Once the customer deletion has been fully processed,
-the customer will not be returned in the API.
-
-
-On successful processing, this returns an empty dictionary (`{}`) in the API.
-
-### Example Usage
-
-```typescript
-import { Orb } from "orb-billing";
-import { DeleteCustomerRequest } from "orb-billing/dist/sdk/models/operations";
-
-(async() => {
-  const sdk = new Orb({
-    security: {
-      apiKey: "",
-    },
-  });
-const customerId: string = "program";
-
-  const res = await sdk.customer.delete(customerId);
-
-  if (res.statusCode == 200) {
-    // handle response
-  }
-})();
-```
-
-### Parameters
-
-| Parameter                                                    | Type                                                         | Required                                                     | Description                                                  |
-| ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
-| `customerId`                                                 | *string*                                                     | :heavy_check_mark:                                           | N/A                                                          |
-| `config`                                                     | [AxiosRequestConfig](https://axios-http.com/docs/req_config) | :heavy_minus_sign:                                           | Available config options for making requests.                |
-
-
-### Response
-
-**Promise<[operations.DeleteCustomerResponse](../../models/operations/deletecustomerresponse.md)>**
-
-
-## fetch
-
-This endpoint is used to fetch customer details given an identifier. If the `Customer` is in the process of being deleted,
-only the properties `id` and `deleted: true` will be returned.
-
-See the [Customer resource](../guides/core-concepts.mdx#customer) for a full discussion of the Customer model.
-
-### Example Usage
-
-```typescript
-import { Orb } from "orb-billing";
-import { FetchCustomerRequest } from "orb-billing/dist/sdk/models/operations";
-
-(async() => {
-  const sdk = new Orb({
-    security: {
-      apiKey: "",
-    },
-  });
-const customerId: string = "grateful";
-
-  const res = await sdk.customer.fetch(customerId);
-
-  if (res.statusCode == 200) {
-    // handle response
-  }
-})();
-```
-
-### Parameters
-
-| Parameter                                                    | Type                                                         | Required                                                     | Description                                                  |
-| ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
-| `customerId`                                                 | *string*                                                     | :heavy_check_mark:                                           | N/A                                                          |
-| `config`                                                     | [AxiosRequestConfig](https://axios-http.com/docs/req_config) | :heavy_minus_sign:                                           | Available config options for making requests.                |
-
-
-### Response
-
-**Promise<[operations.FetchCustomerResponse](../../models/operations/fetchcustomerresponse.md)>**
-
-
-## fetchByExternalId
-
-This endpoint is used to fetch customer details given an `external_customer_id` (see
-[Customer ID Aliases](../guides/events-and-metrics/customer-aliases)).
-
-Note that the resource and semantics of this endpoint exactly mirror [Get Customer](fetch-customer).
-
-### Example Usage
-
-```typescript
-import { Orb } from "orb-billing";
-import { FetchCustomerExternalIdRequest } from "orb-billing/dist/sdk/models/operations";
-
-(async() => {
-  const sdk = new Orb({
-    security: {
-      apiKey: "",
-    },
-  });
-const externalCustomerId: string = "Technician";
-
-  const res = await sdk.customer.fetchByExternalId(externalCustomerId);
-
-  if (res.statusCode == 200) {
-    // handle response
-  }
-})();
-```
-
-### Parameters
-
-| Parameter                                                    | Type                                                         | Required                                                     | Description                                                  |
-| ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
-| `externalCustomerId`                                         | *string*                                                     | :heavy_check_mark:                                           | N/A                                                          |
-| `config`                                                     | [AxiosRequestConfig](https://axios-http.com/docs/req_config) | :heavy_minus_sign:                                           | Available config options for making requests.                |
-
-
-### Response
-
-**Promise<[operations.FetchCustomerExternalIdResponse](../../models/operations/fetchcustomerexternalidresponse.md)>**
-
-
-## fetchCosts
-
-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.
-
-### Example Usage
-
-```typescript
-import { Orb } from "orb-billing";
-import { FetchCustomerCostsViewModeViewMode } from "orb-billing/dist/sdk/models/operations";
-
-(async() => {
-  const sdk = new Orb({
-    security: {
-      apiKey: "",
-    },
-  });
-
-  const res = await sdk.customer.fetchCosts({
-    customerId: "disintermediate",
-    timeframeEnd: new Date("2022-03-01T05:00:00Z"),
-    timeframeStart: new Date("2022-02-01T05:00:00Z"),
-  });
-
-  if (res.statusCode == 200) {
-    // handle response
-  }
-})();
-```
-
-### Parameters
-
-| Parameter                                                                                    | Type                                                                                         | Required                                                                                     | Description                                                                                  |
-| -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
-| `request`                                                                                    | [operations.FetchCustomerCostsRequest](../../models/operations/fetchcustomercostsrequest.md) | :heavy_check_mark:                                                                           | The request object to use for the request.                                                   |
-| `config`                                                                                     | [AxiosRequestConfig](https://axios-http.com/docs/req_config)                                 | :heavy_minus_sign:                                                                           | Available config options for making requests.                                                |
-
-
-### Response
-
-**Promise<[operations.FetchCustomerCostsResponse](../../models/operations/fetchcustomercostsresponse.md)>**
-
-
-## fetchCostsByExternalId
-
-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.
-
-### Example Usage
-
-```typescript
-import { Orb } from "orb-billing";
-import { FetchCustomerCostsExternalIdViewModeViewMode } from "orb-billing/dist/sdk/models/operations";
-
-(async() => {
-  const sdk = new Orb({
-    security: {
-      apiKey: "",
-    },
-  });
-
-  const res = await sdk.customer.fetchCostsByExternalId({
-    externalCustomerId: "TLS Gadolinium Music",
-    timeframeEnd: new Date("2022-03-01T05:00:00Z"),
-    timeframeStart: new Date("2022-02-01T05:00:00Z"),
-  });
-
-  if (res.statusCode == 200) {
-    // handle response
-  }
-})();
-```
-
-### Parameters
-
-| Parameter                                                                                                        | Type                                                                                                             | Required                                                                                                         | Description                                                                                                      |
-| ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
-| `request`                                                                                                        | [operations.FetchCustomerCostsExternalIdRequest](../../models/operations/fetchcustomercostsexternalidrequest.md) | :heavy_check_mark:                                                                                               | The request object to use for the request.                                                                       |
-| `config`                                                                                                         | [AxiosRequestConfig](https://axios-http.com/docs/req_config)                                                     | :heavy_minus_sign:                                                                                               | Available config options for making requests.                                                                    |
-
-
-### Response
-
-**Promise<[operations.FetchCustomerCostsExternalIdResponse](../../models/operations/fetchcustomercostsexternalidresponse.md)>**
-
-
-## list
-
-This endpoint returns a list of all customers for an account.
-The list of customers is ordered starting from the most recently created customer.
-This endpoint follows Orb's [standardized pagination format](../reference/pagination).
-
-See [Customer](../guides/concepts#customer) for an overview of the customer model.
-
-### Example Usage
-
-```typescript
-import { Orb } from "orb-billing";
-
-(async() => {
-  const sdk = new Orb({
-    security: {
-      apiKey: "",
-    },
-  });
-
-  const res = await sdk.customer.list({});
-
-  if (res.statusCode == 200) {
-    // handle response
-  }
-})();
-```
-
-### Parameters
-
-| Parameter                                                                          | Type                                                                               | Required                                                                           | Description                                                                        |
-| ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
-| `request`                                                                          | [operations.ListCustomersRequest](../../models/operations/listcustomersrequest.md) | :heavy_check_mark:                                                                 | The request object to use for the request.                                         |
-| `config`                                                                           | [AxiosRequestConfig](https://axios-http.com/docs/req_config)                       | :heavy_minus_sign:                                                                 | Available config options for making requests.                                      |
-
-
-### Response
-
-**Promise<[operations.ListCustomersResponse](../../models/operations/listcustomersresponse.md)>**
-
-
-## listBalanceTransactions
-
-## The customer balance
-
-The customer balance is an amount in the customer's currency, which Orb automatically applies to subsequent
-invoices. This balance can be adjusted manually via Orb's webapp on the customer details page. You can use this
-balance to provide a fixed mid-period credit to the customer. Commonly, this is done due to system downtime/SLA
-violation, or an adhoc adjustment discussed with the customer.
-
-If the balance is a positive value at the time of invoicing, it represents that the customer has credit that should
-be used to offset the amount due on the next issued invoice. In this case, Orb will automatically reduce the next
-invoice by the balance amount, and roll over any remaining balance if the invoice is fully discounted.
-
-If the balance is a negative value at the time of invoicing, Orb will increase the invoice's amount due with a
-positive adjustment, and reset the balance to 0.
-
-This endpoint retrieves all customer balance transactions in reverse chronological order for a single customer,
-providing a complete audit trail of all adjustments and invoice applications.
-
-## Eligibility
-
-The customer balance can only be applied to invoices or adjusted manually if invoices are not synced to a separate
-invoicing provider. If a payment gateway such as Stripe is used, the balance will be applied to the invoice before
-forwarding payment to the gateway.
-
-### Example Usage
-
-```typescript
-import { Orb } from "orb-billing";
-
-(async() => {
-  const sdk = new Orb({
-    security: {
-      apiKey: "",
-    },
-  });
-
-  const res = await sdk.customer.listBalanceTransactions({
-    customerId: "than",
-  });
-
-  if (res.statusCode == 200) {
-    // handle response
-  }
-})();
-```
-
-### Parameters
-
-| Parameter                                                                                              | Type                                                                                                   | Required                                                                                               | Description                                                                                            |
-| ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
-| `request`                                                                                              | [operations.ListBalanceTransactionsRequest](../../models/operations/listbalancetransactionsrequest.md) | :heavy_check_mark:                                                                                     | The request object to use for the request.                                                             |
-| `config`                                                                                               | [AxiosRequestConfig](https://axios-http.com/docs/req_config)                                           | :heavy_minus_sign:                                                                                     | Available config options for making requests.                                                          |
-
-
-### Response
-
-**Promise<[operations.ListBalanceTransactionsResponse](../../models/operations/listbalancetransactionsresponse.md)>**
-
-
-## updateByExternalId
-
-This endpoint is used to update customer details given an `external_customer_id`
-(see [Customer ID Aliases](../guides/events-and-metrics/customer-aliases)).
-Note that the resource and semantics of this
-endpoint exactly mirror [Update Customer](update-customer).
-
-### Example Usage
-
-```typescript
-import { Orb } from "orb-billing";
-import { UpdateCustomerExternalIdRequest } from "orb-billing/dist/sdk/models/operations";
-import {
-  AccountingProviderConfig,
-  AddressInput,
-  CustomerTaxId,
-  EditCustomer,
-  EditCustomerMetadata,
-  EditCustomerPaymentProvider,
-  NewAccountingSyncConfiguration,
-  NewReportingConfiguration,
-} from "orb-billing/dist/sdk/models/shared";
-
-(async() => {
-  const sdk = new Orb({
-    security: {
-      apiKey: "",
-    },
-  });
-const externalCustomerId: string = "Bicycle";
-const editCustomer: EditCustomer = {
-  accountingSyncConfiguration: {
-    accountingProviders: [
-      {
-        externalProviderId: "Roselyn",
-        providerType: "Lesotho Rap",
-      },
-    ],
-  },
-  additionalEmails: [
-    "showboat",
-  ],
-  billingAddress: {},
-  metadata: {},
-  reportingConfiguration: {
-    exempt: false,
-  },
-  shippingAddress: {},
-  taxId: {
-    country: "Isle of Man",
-    type: "tesla",
-    value: "Branding",
-  },
-};
-
-  const res = await sdk.customer.updateByExternalId(externalCustomerId, editCustomer);
-
-  if (res.statusCode == 200) {
-    // handle response
-  }
-})();
-```
-
-### Parameters
-
-| Parameter                                                    | Type                                                         | Required                                                     | Description                                                  |
-| ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
-| `externalCustomerId`                                         | *string*                                                     | :heavy_check_mark:                                           | N/A                                                          |
-| `editCustomer`                                               | [shared.EditCustomer](../../models/shared/editcustomer.md)   | :heavy_minus_sign:                                           | N/A                                                          |
-| `config`                                                     | [AxiosRequestConfig](https://axios-http.com/docs/req_config) | :heavy_minus_sign:                                           | Available config options for making requests.                |
-
-
-### Response
-
-**Promise<[operations.UpdateCustomerExternalIdResponse](../../models/operations/updatecustomerexternalidresponse.md)>**
-
-
-## updateCustomer
-
-This endpoint can be used to update the `payment_provider`, `payment_provider_id`, `name`, `email`, `email_delivery`, `tax_id`,
-`auto_collection`, `metadata`, `shipping_address`, `billing_address`, and `additional_emails` of an existing customer.
-"Other fields on a customer are currently immutable.
-
-### Example Usage
-
-```typescript
-import { Orb } from "orb-billing";
-import { UpdateCustomerRequest } from "orb-billing/dist/sdk/models/operations";
-import {
-  AccountingProviderConfig,
-  AddressInput,
-  CustomerTaxId,
-  EditCustomer,
-  EditCustomerMetadata,
-  EditCustomerPaymentProvider,
-  NewAccountingSyncConfiguration,
-  NewReportingConfiguration,
-} from "orb-billing/dist/sdk/models/shared";
-
-(async() => {
-  const sdk = new Orb({
-    security: {
-      apiKey: "",
-    },
-  });
-const customerId: string = "Gibraltar";
-const editCustomer: EditCustomer = {
-  accountingSyncConfiguration: {
-    accountingProviders: [
-      {
-        externalProviderId: "Electric",
-        providerType: "Mobility whitewash",
-      },
-    ],
-  },
-  additionalEmails: [
-    "Southeast",
-  ],
-  billingAddress: {},
-  metadata: {},
-  reportingConfiguration: {
-    exempt: false,
-  },
-  shippingAddress: {},
-  taxId: {
-    country: "Luxembourg",
-    type: "program",
-    value: "Car Rufiyaa",
-  },
-};
-
-  const res = await sdk.customer.updateCustomer(customerId, editCustomer);
-
-  if (res.statusCode == 200) {
-    // handle response
-  }
-})();
-```
-
-### Parameters
-
-| Parameter                                                    | Type                                                         | Required                                                     | Description                                                  |
-| ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
-| `customerId`                                                 | *string*                                                     | :heavy_check_mark:                                           | N/A                                                          |
-| `editCustomer`                                               | [shared.EditCustomer](../../models/shared/editcustomer.md)   | :heavy_minus_sign:                                           | N/A                                                          |
-| `config`                                                     | [AxiosRequestConfig](https://axios-http.com/docs/req_config) | :heavy_minus_sign:                                           | Available config options for making requests.                |
-
-
-### Response
-
-**Promise<[operations.UpdateCustomerResponse](../../models/operations/updatecustomerresponse.md)>**
-