orb-billing 1.0.1 → 1.19.5

package/docs/sdks/customer/README.md

@@ -0,0 +1,1129 @@
+# 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 { AmendUsageResponse } from "orb-billing/dist/sdk/models/operations";
+
+const sdk = new Orb({
+  security: {
+    apiKeyAuth: "",
+  },
+});
+
+sdk.customer.amend({
+  updateEvent: {
+    customerId: "driver",
+    eventName: "bypass",
+    externalCustomerId: "Kids",
+    properties: {},
+    timestamp: new Date("2020-12-09T16:09:53Z"),
+  },
+  customerId: "previous enchanting",
+  timeframeEnd: new Date("2021-03-06T03:20:54.516Z"),
+  timeframeStart: new Date("2022-10-30T03:17:34.038Z"),
+}).then((res: AmendUsageResponse) => {
+  if (res.statusCode == 200) {
+    // handle response
+  }
+});
+```
+
+### Parameters
+
+| Parameter                                                                    | Type                                                                         | Required                                                                     | Description                                                                  |
+| ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| `request`                                                                    | [operations.AmendUsageRequest](../../models/operations/amendusagerequest.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.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 { AmendUsageExternalCustomerIdResponse } from "orb-billing/dist/sdk/models/operations";
+
+const sdk = new Orb({
+  security: {
+    apiKeyAuth: "",
+  },
+});
+
+sdk.customer.amendByExternalId({
+  updateEvent: {
+    customerId: "woman",
+    eventName: "Orchestrator",
+    externalCustomerId: "Highway Gloves Androgynous",
+    properties: {},
+    timestamp: new Date("2020-12-09T16:09:53Z"),
+  },
+  externalCustomerId: "Hatchback Gloves powerless",
+  timeframeEnd: new Date("2021-05-18T15:51:03.859Z"),
+  timeframeStart: new Date("2022-10-03T18:15:53.258Z"),
+}).then((res: AmendUsageExternalCustomerIdResponse) => {
+  if (res.statusCode == 200) {
+    // handle response
+  }
+});
+```
+
+### Parameters
+
+| Parameter                                                                                                        | Type                                                                                                             | Required                                                                                                         | Description                                                                                                      |
+| ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `request`                                                                                                        | [operations.AmendUsageExternalCustomerIdRequest](../../models/operations/amendusageexternalcustomeridrequest.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.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 { CreateCustomerResponse } from "orb-billing/dist/sdk/models/operations";
+import { NewCustomerPaymentProvider } from "orb-billing/dist/sdk/models/shared";
+
+const sdk = new Orb({
+  security: {
+    apiKeyAuth: "",
+  },
+});
+
+sdk.customer.create({
+  accountingSyncConfiguration: {
+    accountingProviders: [
+      {
+        externalProviderId: "bluetooth Extended",
+        providerType: "blue",
+      },
+    ],
+    excluded: false,
+  },
+  additionalEmails: [
+    "shred",
+  ],
+  autoCollection: false,
+  billingAddress: {
+    city: "Fort Silas",
+    country: "Afghanistan",
+    line1: "orange Northwest",
+    line2: "SUV quantify Polestar",
+    postalCode: "96302",
+    state: "South Intelligent Fish",
+  },
+  currency: "Barbados Dollar",
+  email: "Enoch41@hotmail.com",
+  emailDelivery: false,
+  externalCustomerId: "Metal",
+  metadata: {},
+  name: "Direct metrics",
+  paymentProvider: NewCustomerPaymentProvider.Quickbooks,
+  paymentProviderId: "Interactions Senior Mouse",
+  reportingConfiguration: {
+    exempt: false,
+  },
+  shippingAddress: {
+    city: "Fort Juddborough",
+    country: "Anguilla",
+    line1: "Investor",
+    line2: "azure Dollar",
+    postalCode: "72679",
+    state: "Sausages",
+  },
+  taxId: {
+    country: "Sao Tome and Principe",
+    type: "City meanwhile incompatible",
+    value: "Folk South digital",
+  },
+  timezone: "Europe/Ljubljana",
+}).then((res: CreateCustomerResponse) => {
+  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 { CreateCustomerBalanceTransactionResponse } from "orb-billing/dist/sdk/models/operations";
+import { NewCustomerBalanceTransactionType } from "orb-billing/dist/sdk/models/shared";
+
+const sdk = new Orb({
+  security: {
+    apiKeyAuth: "",
+  },
+});
+
+sdk.customer.createBalanceTransaction({
+  newCustomerBalanceTransaction: {
+    amount: "221.39",
+    description: "Diverse contextually-based website",
+    type: NewCustomerBalanceTransactionType.Increment,
+  },
+  customerId: "Northwest",
+}).then((res: CreateCustomerBalanceTransactionResponse) => {
+  if (res.statusCode == 200) {
+    // handle response
+  }
+});
+```
+
+### Parameters
+
+| Parameter                                                                                                                | Type                                                                                                                     | Required                                                                                                                 | Description                                                                                                              |
+| ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
+| `request`                                                                                                                | [operations.CreateCustomerBalanceTransactionRequest](../../models/operations/createcustomerbalancetransactionrequest.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.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 { DeleteCustomerResponse } from "orb-billing/dist/sdk/models/operations";
+
+const sdk = new Orb({
+  security: {
+    apiKeyAuth: "",
+  },
+});
+
+sdk.customer.delete({
+  customerId: "Van complexity",
+}).then((res: DeleteCustomerResponse) => {
+  if (res.statusCode == 200) {
+    // handle response
+  }
+});
+```
+
+### Parameters
+
+| Parameter                                                                            | Type                                                                                 | Required                                                                             | Description                                                                          |
+| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
+| `request`                                                                            | [operations.DeleteCustomerRequest](../../models/operations/deletecustomerrequest.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.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 { FetchCustomerResponse } from "orb-billing/dist/sdk/models/operations";
+
+const sdk = new Orb({
+  security: {
+    apiKeyAuth: "",
+  },
+});
+
+sdk.customer.fetch({
+  customerId: "Total Honda Southeast",
+}).then((res: FetchCustomerResponse) => {
+  if (res.statusCode == 200) {
+    // handle response
+  }
+});
+```
+
+### Parameters
+
+| Parameter                                                                          | Type                                                                               | Required                                                                           | Description                                                                        |
+| ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `request`                                                                          | [operations.FetchCustomerRequest](../../models/operations/fetchcustomerrequest.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.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 { FetchCustomerExternalIdResponse } from "orb-billing/dist/sdk/models/operations";
+
+const sdk = new Orb({
+  security: {
+    apiKeyAuth: "",
+  },
+});
+
+sdk.customer.fetchByExternalId({
+  externalCustomerId: "Loan Gasoline ping",
+}).then((res: FetchCustomerExternalIdResponse) => {
+  if (res.statusCode == 200) {
+    // handle response
+  }
+});
+```
+
+### Parameters
+
+| Parameter                                                                                              | Type                                                                                                   | Required                                                                                               | Description                                                                                            |
+| ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
+| `request`                                                                                              | [operations.FetchCustomerExternalIdRequest](../../models/operations/fetchcustomerexternalidrequest.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.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 { FetchCustomerCostsResponse, FetchCustomerCostsViewModeViewMode } from "orb-billing/dist/sdk/models/operations";
+
+const sdk = new Orb({
+  security: {
+    apiKeyAuth: "",
+  },
+});
+
+sdk.customer.fetchCosts({
+  customerId: "disintermediate",
+  groupBy: "Coupe North Handmade",
+  timeframeEnd: new Date("2022-03-01T05:00:00Z"),
+  timeframeStart: new Date("2022-02-01T05:00:00Z"),
+  viewMode: FetchCustomerCostsViewModeViewMode.Periodic,
+}).then((res: FetchCustomerCostsResponse) => {
+  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 {
+  FetchCustomerCostsExternalIdResponse,
+  FetchCustomerCostsExternalIdViewModeViewMode,
+} from "orb-billing/dist/sdk/models/operations";
+
+const sdk = new Orb({
+  security: {
+    apiKeyAuth: "",
+  },
+});
+
+sdk.customer.fetchCostsByExternalId({
+  externalCustomerId: "TLS Gadolinium Music",
+  groupBy: "Sedan Tuna",
+  timeframeEnd: new Date("2022-03-01T05:00:00Z"),
+  timeframeStart: new Date("2022-02-01T05:00:00Z"),
+  viewMode: FetchCustomerCostsExternalIdViewModeViewMode.Periodic,
+}).then((res: FetchCustomerCostsExternalIdResponse) => {
+  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";
+import { ListCustomersResponse } from "orb-billing/dist/sdk/models/operations";
+
+const sdk = new Orb({
+  security: {
+    apiKeyAuth: "",
+  },
+});
+
+sdk.customer.list({
+  createdAtGt: new Date("2023-04-22T14:13:10.937Z"),
+  createdAtGte: new Date("2021-04-20T09:15:20.369Z"),
+  createdAtLt: new Date("2022-08-23T06:18:16.401Z"),
+  createdAtLte: new Date("2021-10-10T03:01:48.624Z"),
+  cursor: "Canada that orchid",
+  limit: 282238,
+}).then((res: ListCustomersResponse) => {
+  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";
+import { ListBalanceTransactionsResponse } from "orb-billing/dist/sdk/models/operations";
+
+const sdk = new Orb({
+  security: {
+    apiKeyAuth: "",
+  },
+});
+
+sdk.customer.listBalanceTransactions({
+  cursor: "than",
+  customerId: "Facilitator extension",
+  limit: 717443,
+  operationTimeGt: new Date("2021-01-05T14:12:58.642Z"),
+  operationTimeGte: new Date("2021-07-29T02:13:45.075Z"),
+  operationTimeLt: new Date("2021-01-31T23:25:30.251Z"),
+  operationTimeLte: new Date("2023-04-23T18:28:37.185Z"),
+}).then((res: ListBalanceTransactionsResponse) => {
+  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 { UpdateCustomerExternalIdResponse } from "orb-billing/dist/sdk/models/operations";
+import { EditCustomerPaymentProvider } from "orb-billing/dist/sdk/models/shared";
+
+const sdk = new Orb({
+  security: {
+    apiKeyAuth: "",
+  },
+});
+
+sdk.customer.updateByExternalId({
+  editCustomer: {
+    accountingSyncConfiguration: {
+      accountingProviders: [
+        {
+          externalProviderId: "Concrete Extended Rock",
+          providerType: "Rap showboat",
+        },
+      ],
+      excluded: false,
+    },
+    additionalEmails: [
+      "Peso",
+    ],
+    autoCollection: false,
+    billingAddress: {
+      city: "Biankafurt",
+      country: "Northern Mariana Islands",
+      line1: "invoice",
+      line2: "invoice web",
+      postalCode: "37946-8361",
+      state: "Wagon",
+    },
+    currency: "Namibia Dollar",
+    email: "Van84@hotmail.com",
+    emailDelivery: false,
+    externalCustomerId: "Home",
+    metadata: {},
+    name: "grey",
+    paymentProvider: EditCustomerPaymentProvider.BillCom,
+    paymentProviderId: "composite",
+    reportingConfiguration: {
+      exempt: false,
+    },
+    shippingAddress: {
+      city: "East Kenna",
+      country: "Monaco",
+      line1: "Investment",
+      line2: "bypass Tactics",
+      postalCode: "39092",
+      state: "Steel",
+    },
+    taxId: {
+      country: "Heard Island and McDonald Islands",
+      type: "Producer",
+      value: "Jannie",
+    },
+  },
+  externalCustomerId: "mobile",
+}).then((res: UpdateCustomerExternalIdResponse) => {
+  if (res.statusCode == 200) {
+    // handle response
+  }
+});
+```
+
+### Parameters
+
+| Parameter                                                                                                | Type                                                                                                     | Required                                                                                                 | Description                                                                                              |
+| -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `request`                                                                                                | [operations.UpdateCustomerExternalIdRequest](../../models/operations/updatecustomerexternalidrequest.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.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 { UpdateCustomerResponse } from "orb-billing/dist/sdk/models/operations";
+import { EditCustomerPaymentProvider } from "orb-billing/dist/sdk/models/shared";
+
+const sdk = new Orb({
+  security: {
+    apiKeyAuth: "",
+  },
+});
+
+sdk.customer.updateCustomer({
+  editCustomer: {
+    accountingSyncConfiguration: {
+      accountingProviders: [
+        {
+          externalProviderId: "Electric",
+          providerType: "Mobility whitewash",
+        },
+      ],
+      excluded: false,
+    },
+    additionalEmails: [
+      "Southeast",
+    ],
+    autoCollection: false,
+    billingAddress: {
+      city: "Daynastad",
+      country: "Dominican Republic",
+      line1: "Car Rufiyaa",
+      line2: "deposit synergize",
+      postalCode: "02403",
+      state: "oblong reckless Molybdenum",
+    },
+    currency: "UIC-Franc",
+    email: "Taryn87@gmail.com",
+    emailDelivery: false,
+    externalCustomerId: "circuit Account",
+    metadata: {},
+    name: "South circumstance Corporate",
+    paymentProvider: EditCustomerPaymentProvider.Quickbooks,
+    paymentProviderId: "GB female well",
+    reportingConfiguration: {
+      exempt: false,
+    },
+    shippingAddress: {
+      city: "New Estelleburgh",
+      country: "Cape Verde",
+      line1: "dole payment",
+      line2: "Durham Funk",
+      postalCode: "54768-2343",
+      state: "plum bus Tuna",
+    },
+    taxId: {
+      country: "Italy",
+      type: "wherever Molybdenum",
+      value: "SUV Lesotho",
+    },
+  },
+  customerId: "Global Hop Pine",
+}).then((res: UpdateCustomerResponse) => {
+  if (res.statusCode == 200) {
+    // handle response
+  }
+});
+```
+
+### Parameters
+
+| Parameter                                                                            | Type                                                                                 | Required                                                                             | Description                                                                          |
+| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
+| `request`                                                                            | [operations.UpdateCustomerRequest](../../models/operations/updatecustomerrequest.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.UpdateCustomerResponse](../../models/operations/updatecustomerresponse.md)>**
+