orb-billing 1.0.1 → 1.19.5

package/docs/sdks/credit/README.md

@@ -0,0 +1,605 @@
+# Credit
+(*credit*)
+
+## Overview
+
+The [Credit Ledger Entry resource](/guides/product-catalog/prepurchase) models prepaid credits within Orb.
+
+### Available Operations
+
+* [addByExternalId](#addbyexternalid) - Create ledger entry by external ID
+* [create](#create) - Create ledger entry
+* [fetchBalance](#fetchbalance) - Fetch customer credit balance
+* [fetchBalanceByExternalId](#fetchbalancebyexternalid) - Fetch customer credit balance by external customer id
+* [fetchLedger](#fetchledger) - Fetch customer credits ledger
+* [fetchLedgerByExternalId](#fetchledgerbyexternalid) - Fetch customer credits ledger by external ID
+
+## addByExternalId
+
+This endpoint allows you to create a new ledger entry for a specified customer's balance. This can be used to
+increment balance, deduct credits, and change the expiry date of existing credits.
+
+## Effects of adding a ledger entry
+1. After calling this endpoint, [Fetch Credit Balance](fetch-customer-credits) will return a credit block that
+  represents the changes (i.e. balance changes or transfers).
+2. A ledger entry will be added to the credits ledger for this customer, and therefore returned in the
+  [View Credits Ledger](fetch-customer-credits) response as well as serialized in the response to this request. In
+  the case of deductions without a specified block, multiple ledger entries may be created if the deduction spans
+  credit blocks.
+3. If `invoice_settings` is specified, an invoice will be created that reflects the cost of the credits (based on
+  `amount` and `per_unit_cost_basis`).
+
+## Adding credits
+  Adding credits is done by creating an entry of type `increment`. This requires the caller to specify a number of
+  credits as well as an optional expiry date in `YYYY-MM-DD` format. Orb also recommends specifying a description
+  to assist with auditing. When adding credits, the caller can also specify a cost basis per-credit, to indicate
+  how much in USD a customer paid for a single credit in a block. This can later be used for revenue recognition.
+
+The following snippet illustrates a sample request body to increment credits which will expire in January of 2022.
+
+```json
+{
+  "entry_type": "increment",
+  "amount": 100,
+  "expiry_date": "2022-12-28",
+  "per_unit_cost_basis": "0.20",
+  "description": "Purchased 100 credits"
+}
+```
+
+Note that by default, Orb will always first increment any _negative_ balance in existing blocks before adding the
+remaining amount to the desired credit block.
+
+### Invoicing for credits
+By default, Orb manipulates the credit ledger but does not charge for credits. However, if you pass
+`invoice_settings` in the body of this request, Orb will also generate a one-off invoice for the customer for the
+credits pre-purchase. Note that you _must_ provide the `per_unit_cost_basis`, since the total charges on the
+invoice are calculated by multiplying the cost basis with the number of credit units added.
+
+## Deducting Credits
+Orb allows you to deduct credits from a customer by creating an entry of type `decrement`. Orb matches the
+algorithm for automatic deductions for determining which credit blocks to decrement from. In the case that the
+deduction leads to multiple ledger entries, the response from this endpoint will be the final deduction. Orb also
+optionally allows specifying a description to assist with auditing.
+
+The following snippet illustrates a sample request body to decrement credits.
+
+```json
+{
+  "entry_type": "decrement",
+  "amount": 20,
+  "description": "Removing excess credits"
+}
+```
+
+## Changing credits expiry
+If you'd like to change when existing credits expire, you should create a ledger entry of type `expiration_change`.
+For this entry, the required parameter `expiry_date` identifies the _originating_ block, and the required parameter
+`target_expiry_date` identifies when the transferred credits should now expire. A new credit block will be created
+with expiry date `target_expiry_date`, with the same cost basis data as the original credit block, if present.
+
+Note that the balance of the block with the given `expiry_date` must be at least equal to the desired transfer
+amount determined by the `amount` parameter.
+
+The following snippet illustrates a sample request body to extend the expiration date of credits by one year:
+
+```json
+{
+  "entry_type": "expiration_change",
+  "amount": 10,
+  "expiry_date": "2022-12-28",
+  "block_id": "UiUhFWeLHPrBY4Ad",
+  "target_expiry_date": "2023-12-28",
+  "description": "Extending credit validity"
+}
+```
+
+## Voiding credits
+
+If you'd like to void a credit block, create a ledger entry of type `void`. For this entry, `block_id` is required
+to identify the block, and `amount` indicates how many credits to void, up to the block's initial balance. Pass
+in a `void_reason` of `refund` if the void is due to a refund.
+
+## Amendment
+
+If you'd like to undo a decrement on a credit block, create a ledger entry of type `amendment`. For this entry, `block_id`
+is required to identify the block that was originally decremented from, and `amount` indicates how many credits to return
+to the customer, up to the block's initial balance.
+
+### Example Usage
+
+```typescript
+import { Orb } from "orb-billing";
+import { CreateLedgerEntryExternalIdResponse } from "orb-billing/dist/sdk/models/operations";
+import {
+  AddAmendmentCreditLedgerEntryRequestParamsEntryType,
+  AddDecrementCreditLedgerEntryRequestParamsEntryType,
+  AddExpirationChangeCreditLedgerEntryRequestParamsEntryType,
+  AddIncrementCreditLedgerEntryRequestParamsEntryType,
+  AddVoidCreditLedgerEntryRequestParamsEntryType,
+  AddVoidCreditLedgerEntryRequestParamsVoidReason,
+} from "orb-billing/dist/sdk/models/shared";
+import { RFCDate } from "orb-billing/dist/sdk/types";
+
+const sdk = new Orb({
+  security: {
+    apiKeyAuth: "",
+  },
+});
+
+sdk.credit.addByExternalId({
+  requestBody: {
+    amount: "543.93",
+    blockId: "Southwest Silver",
+    description: "Fully-configurable object-oriented projection",
+    entryType: AddAmendmentCreditLedgerEntryRequestParamsEntryType.Amendment,
+    metadata: {},
+  },
+  externalCustomerId: "misspend Rubidium",
+}).then((res: CreateLedgerEntryExternalIdResponse) => {
+  if (res.statusCode == 200) {
+    // handle response
+  }
+});
+```
+
+### Parameters
+
+| Parameter                                                                                                      | Type                                                                                                           | Required                                                                                                       | Description                                                                                                    |
+| -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `request`                                                                                                      | [operations.CreateLedgerEntryExternalIdRequest](../../models/operations/createledgerentryexternalidrequest.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.CreateLedgerEntryExternalIdResponse](../../models/operations/createledgerentryexternalidresponse.md)>**
+
+
+## create
+
+This endpoint allows you to create a new ledger entry for a specified customer's balance. This can be used to
+increment balance, deduct credits, and change the expiry date of existing credits.
+
+## Effects of adding a ledger entry
+1. After calling this endpoint, [Fetch Credit Balance](fetch-customer-credits) will return a credit block that
+  represents the changes (i.e. balance changes or transfers).
+2. A ledger entry will be added to the credits ledger for this customer, and therefore returned in the
+  [View Credits Ledger](fetch-customer-credits) response as well as serialized in the response to this request. In
+  the case of deductions without a specified block, multiple ledger entries may be created if the deduction spans
+  credit blocks.
+3. If `invoice_settings` is specified, an invoice will be created that reflects the cost of the credits (based on
+  `amount` and `per_unit_cost_basis`).
+
+## Adding credits
+  Adding credits is done by creating an entry of type `increment`. This requires the caller to specify a number of
+  credits as well as an optional expiry date in `YYYY-MM-DD` format. Orb also recommends specifying a description
+  to assist with auditing. When adding credits, the caller can also specify a cost basis per-credit, to indicate
+  how much in USD a customer paid for a single credit in a block. This can later be used for revenue recognition.
+
+The following snippet illustrates a sample request body to increment credits which will expire in January of 2022.
+
+```json
+{
+  "entry_type": "increment",
+  "amount": 100,
+  "expiry_date": "2022-12-28",
+  "per_unit_cost_basis": "0.20",
+  "description": "Purchased 100 credits"
+}
+```
+
+Note that by default, Orb will always first increment any _negative_ balance in existing blocks before adding the
+remaining amount to the desired credit block.
+
+### Invoicing for credits
+By default, Orb manipulates the credit ledger but does not charge for credits. However, if you pass
+`invoice_settings` in the body of this request, Orb will also generate a one-off invoice for the customer for the
+credits pre-purchase. Note that you _must_ provide the `per_unit_cost_basis`, since the total charges on the
+invoice are calculated by multiplying the cost basis with the number of credit units added.
+
+## Deducting Credits
+Orb allows you to deduct credits from a customer by creating an entry of type `decrement`. Orb matches the
+algorithm for automatic deductions for determining which credit blocks to decrement from. In the case that the
+deduction leads to multiple ledger entries, the response from this endpoint will be the final deduction. Orb also
+optionally allows specifying a description to assist with auditing.
+
+The following snippet illustrates a sample request body to decrement credits.
+
+```json
+{
+  "entry_type": "decrement",
+  "amount": 20,
+  "description": "Removing excess credits"
+}
+```
+
+## Changing credits expiry
+If you'd like to change when existing credits expire, you should create a ledger entry of type `expiration_change`.
+For this entry, the required parameter `expiry_date` identifies the _originating_ block, and the required parameter
+`target_expiry_date` identifies when the transferred credits should now expire. A new credit block will be created
+with expiry date `target_expiry_date`, with the same cost basis data as the original credit block, if present.
+
+Note that the balance of the block with the given `expiry_date` must be at least equal to the desired transfer
+amount determined by the `amount` parameter.
+
+The following snippet illustrates a sample request body to extend the expiration date of credits by one year:
+
+```json
+{
+  "entry_type": "expiration_change",
+  "amount": 10,
+  "expiry_date": "2022-12-28",
+  "block_id": "UiUhFWeLHPrBY4Ad",
+  "target_expiry_date": "2023-12-28",
+  "description": "Extending credit validity"
+}
+```
+
+## Voiding credits
+
+If you'd like to void a credit block, create a ledger entry of type `void`. For this entry, `block_id` is required
+to identify the block, and `amount` indicates how many credits to void, up to the block's initial balance. Pass
+in a `void_reason` of `refund` if the void is due to a refund.
+
+## Amendment
+
+If you'd like to undo a decrement on a credit block, create a ledger entry of type `amendment`. For this entry, `block_id`
+is required to identify the block that was originally decremented from, and `amount` indicates how many credits to return
+to the customer, up to the block's initial balance.
+
+### Example Usage
+
+```typescript
+import { Orb } from "orb-billing";
+import { CreateLedgerEntryResponse } from "orb-billing/dist/sdk/models/operations";
+import {
+  AddAmendmentCreditLedgerEntryRequestParamsEntryType,
+  AddDecrementCreditLedgerEntryRequestParamsEntryType,
+  AddExpirationChangeCreditLedgerEntryRequestParamsEntryType,
+  AddIncrementCreditLedgerEntryRequestParamsEntryType,
+  AddVoidCreditLedgerEntryRequestParamsEntryType,
+  AddVoidCreditLedgerEntryRequestParamsVoidReason,
+} from "orb-billing/dist/sdk/models/shared";
+import { RFCDate } from "orb-billing/dist/sdk/types";
+
+const sdk = new Orb({
+  security: {
+    apiKeyAuth: "",
+  },
+});
+
+sdk.credit.create({
+  requestBody: {
+    amount: 6384.24,
+    blockId: "Money blue shred",
+    description: "Implemented web-enabled success",
+    entryType: AddExpirationChangeCreditLedgerEntryRequestParamsEntryType.ExpirationChange,
+    expiryDate: new RFCDate("2021-01-01"),
+    metadata: {},
+    targetExpiryDate: new RFCDate("2022-05-14"),
+  },
+  customerId: "evolve",
+}).then((res: CreateLedgerEntryResponse) => {
+  if (res.statusCode == 200) {
+    // handle response
+  }
+});
+```
+
+### Parameters
+
+| Parameter                                                                                  | Type                                                                                       | Required                                                                                   | Description                                                                                |
+| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
+| `request`                                                                                  | [operations.CreateLedgerEntryRequest](../../models/operations/createledgerentryrequest.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.CreateLedgerEntryResponse](../../models/operations/createledgerentryresponse.md)>**
+
+
+## fetchBalance
+
+Returns a paginated list of unexpired, non-zero credit blocks for a customer.
+
+### Example Usage
+
+```typescript
+import { Orb } from "orb-billing";
+import { FetchCustomerCreditsResponse } from "orb-billing/dist/sdk/models/operations";
+
+const sdk = new Orb({
+  security: {
+    apiKeyAuth: "",
+  },
+});
+
+sdk.credit.fetchBalance({
+  cursor: "leverage quantifying",
+  customerId: "throughput",
+  limit: 957442,
+}).then((res: FetchCustomerCreditsResponse) => {
+  if (res.statusCode == 200) {
+    // handle response
+  }
+});
+```
+
+### Parameters
+
+| Parameter                                                                                        | Type                                                                                             | Required                                                                                         | Description                                                                                      |
+| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
+| `request`                                                                                        | [operations.FetchCustomerCreditsRequest](../../models/operations/fetchcustomercreditsrequest.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.FetchCustomerCreditsResponse](../../models/operations/fetchcustomercreditsresponse.md)>**
+
+
+## fetchBalanceByExternalId
+
+Returns a paginated list of unexpired, non-zero credit blocks for a customer.
+
+### Example Usage
+
+```typescript
+import { Orb } from "orb-billing";
+import { FetchCustomerCreditsExternalIdResponse } from "orb-billing/dist/sdk/models/operations";
+
+const sdk = new Orb({
+  security: {
+    apiKeyAuth: "",
+  },
+});
+
+sdk.credit.fetchBalanceByExternalId({
+  cursor: "politely libero bad",
+  externalCustomerId: "Plastic Tactics bus",
+  limit: 292281,
+}).then((res: FetchCustomerCreditsExternalIdResponse) => {
+  if (res.statusCode == 200) {
+    // handle response
+  }
+});
+```
+
+### Parameters
+
+| Parameter                                                                                                            | Type                                                                                                                 | Required                                                                                                             | Description                                                                                                          |
+| -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `request`                                                                                                            | [operations.FetchCustomerCreditsExternalIdRequest](../../models/operations/fetchcustomercreditsexternalidrequest.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.FetchCustomerCreditsExternalIdResponse](../../models/operations/fetchcustomercreditsexternalidresponse.md)>**
+
+
+## fetchLedger
+
+The credits ledger provides _auditing_ functionality over Orb's credits system with a list of actions that have
+taken place to modify a customer's credit balance. This [paginated endpoint](../reference/pagination) lists these
+entries, starting from the most recent ledger entry.
+
+More details on using Orb's real-time credit feature are [here](../guides/product-catalog/prepurchase.md).
+
+There are four major types of modifications to credit balance, detailed below.
+
+## Increment
+Credits (which optionally expire on a future date) can be added via the API
+([Add Ledger Entry](create-ledger-entry)). The ledger entry for such an action will always contain the total
+eligible starting and ending balance for the customer at the time the entry was added to the ledger.
+
+## Decrement
+Deductions can occur as a result of an API call to create a ledger entry (see
+[Add Ledger Entry](create-ledger-entry)), or automatically as a result of incurring usage. Both ledger entries
+present the `decrement` entry type.
+
+As usage for a customer is reported into Orb, credits may be deducted according to the customer's plan
+configuration. An automated deduction of this type will result in a ledger entry, also with a starting and ending
+balance. In order to provide better tracing capabilities for automatic deductions, Orb always associates each
+automatic deduction with the `event_id` at the time of ingestion, used to pinpoint _why_ credit deduction took
+place and to ensure that credits are never deducted without an associated usage event.
+
+By default, Orb uses an algorithm that automatically deducts from the *soonest expiring credit block* first in
+order to ensure that all credits are utilized appropriately. As an example, if trial credits with an expiration date
+of 2 weeks from now are present for a customer, they will be used before any deductions take place from a
+non-expiring credit block.
+
+If there are multiple blocks with the same expiration date, Orb will deduct from the block with the
+*lower cost basis* first (ex. trial credits with a $0 cost basis before paid credits with a $5.00 cost basis).
+
+It's also possible for a single usage event's deduction to _span_ credit blocks. In this case, Orb will deduct from
+the next block, ending at the credit block which consists of unexpiring credits. Each of these deductions will lead
+to a _separate_ ledger entry, one per credit block that is deducted from. By default, the customer's total credit
+balance in Orb can be negative as a result of a decrement.
+
+## Expiration change
+The expiry of credits can be changed as a result of the API (See [Add Ledger Entry](create-ledger-entry)). This will
+create a ledger entry that specifies the balance as well as the initial and target expiry dates.
+
+Note that for this entry type, `starting_balance` will equal `ending_balance`, and the `amount` represents the
+balance transferred. The credit block linked to the ledger entry is the source credit block from which there was an
+expiration change
+
+## Credits expiry
+When a set of credits expire on pre-set expiration date, the customer's balance automatically reflects this change
+and adds an entry to the ledger indicating this event. Note that credit expiry should always happen close to a date
+boundary in the customer's timezone.
+
+## Void initiated
+Credit blocks can be voided via the API. The `amount` on this entry corresponds to the number of credits that were
+remaining in the block at time of void. `void_reason` will be populated if the void is created with a reason.
+
+## Void
+When a set of credits is voided, the customer's balance automatically reflects this change and adds an entry to the
+ledger indicating this event.
+
+## Amendment
+When credits are added to a customer's balance as a result of a correction, this entry will be added to the ledger
+to indicate the adjustment of credits.
+
+### Example Usage
+
+```typescript
+import { Orb } from "orb-billing";
+import {
+  FetchCustomerCreditsLedgerEntryStatusEntryStatus,
+  FetchCustomerCreditsLedgerEntryTypeEntryType,
+  FetchCustomerCreditsLedgerResponse,
+} from "orb-billing/dist/sdk/models/operations";
+
+const sdk = new Orb({
+  security: {
+    apiKeyAuth: "",
+  },
+});
+
+sdk.credit.fetchLedger({
+  createdAtGt: new Date("2021-08-07T05:53:42.253Z"),
+  createdAtGte: new Date("2021-03-04T16:26:59.995Z"),
+  createdAtLt: new Date("2022-05-17T01:56:00.143Z"),
+  createdAtLte: new Date("2023-09-07T22:52:03.052Z"),
+  currency: "Guarani",
+  cursor: "District",
+  customerId: "along hertz",
+  entryStatus: FetchCustomerCreditsLedgerEntryStatusEntryStatus.Committed,
+  entryType: FetchCustomerCreditsLedgerEntryTypeEntryType.CreditBlockExpiry,
+  limit: 267714,
+  minimumAmount: "ADP",
+}).then((res: FetchCustomerCreditsLedgerResponse) => {
+  if (res.statusCode == 200) {
+    // handle response
+  }
+});
+```
+
+### Parameters
+
+| Parameter                                                                                                    | Type                                                                                                         | Required                                                                                                     | Description                                                                                                  |
+| ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
+| `request`                                                                                                    | [operations.FetchCustomerCreditsLedgerRequest](../../models/operations/fetchcustomercreditsledgerrequest.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.FetchCustomerCreditsLedgerResponse](../../models/operations/fetchcustomercreditsledgerresponse.md)>**
+
+
+## fetchLedgerByExternalId
+
+The credits ledger provides _auditing_ functionality over Orb's credits system with a list of actions that have
+taken place to modify a customer's credit balance. This [paginated endpoint](../reference/pagination) lists these
+entries, starting from the most recent ledger entry.
+
+More details on using Orb's real-time credit feature are [here](../guides/product-catalog/prepurchase.md).
+
+There are four major types of modifications to credit balance, detailed below.
+
+## Increment
+Credits (which optionally expire on a future date) can be added via the API
+([Add Ledger Entry](create-ledger-entry)). The ledger entry for such an action will always contain the total
+eligible starting and ending balance for the customer at the time the entry was added to the ledger.
+
+## Decrement
+Deductions can occur as a result of an API call to create a ledger entry (see
+[Add Ledger Entry](create-ledger-entry)), or automatically as a result of incurring usage. Both ledger entries
+present the `decrement` entry type.
+
+As usage for a customer is reported into Orb, credits may be deducted according to the customer's plan
+configuration. An automated deduction of this type will result in a ledger entry, also with a starting and ending
+balance. In order to provide better tracing capabilities for automatic deductions, Orb always associates each
+automatic deduction with the `event_id` at the time of ingestion, used to pinpoint _why_ credit deduction took
+place and to ensure that credits are never deducted without an associated usage event.
+
+By default, Orb uses an algorithm that automatically deducts from the *soonest expiring credit block* first in
+order to ensure that all credits are utilized appropriately. As an example, if trial credits with an expiration date
+of 2 weeks from now are present for a customer, they will be used before any deductions take place from a
+non-expiring credit block.
+
+If there are multiple blocks with the same expiration date, Orb will deduct from the block with the
+*lower cost basis* first (ex. trial credits with a $0 cost basis before paid credits with a $5.00 cost basis).
+
+It's also possible for a single usage event's deduction to _span_ credit blocks. In this case, Orb will deduct from
+the next block, ending at the credit block which consists of unexpiring credits. Each of these deductions will lead
+to a _separate_ ledger entry, one per credit block that is deducted from. By default, the customer's total credit
+balance in Orb can be negative as a result of a decrement.
+
+## Expiration change
+The expiry of credits can be changed as a result of the API (See [Add Ledger Entry](create-ledger-entry)). This will
+create a ledger entry that specifies the balance as well as the initial and target expiry dates.
+
+Note that for this entry type, `starting_balance` will equal `ending_balance`, and the `amount` represents the
+balance transferred. The credit block linked to the ledger entry is the source credit block from which there was an
+expiration change
+
+## Credits expiry
+When a set of credits expire on pre-set expiration date, the customer's balance automatically reflects this change
+and adds an entry to the ledger indicating this event. Note that credit expiry should always happen close to a date
+boundary in the customer's timezone.
+
+## Void initiated
+Credit blocks can be voided via the API. The `amount` on this entry corresponds to the number of credits that were
+remaining in the block at time of void. `void_reason` will be populated if the void is created with a reason.
+
+## Void
+When a set of credits is voided, the customer's balance automatically reflects this change and adds an entry to the
+ledger indicating this event.
+
+## Amendment
+When credits are added to a customer's balance as a result of a correction, this entry will be added to the ledger
+to indicate the adjustment of credits.
+
+### Example Usage
+
+```typescript
+import { Orb } from "orb-billing";
+import {
+  FetchCustomerCreditsLedgerExternalIdEntryStatusEntryStatus,
+  FetchCustomerCreditsLedgerExternalIdEntryTypeEntryType,
+  FetchCustomerCreditsLedgerExternalIdResponse,
+} from "orb-billing/dist/sdk/models/operations";
+
+const sdk = new Orb({
+  security: {
+    apiKeyAuth: "",
+  },
+});
+
+sdk.credit.fetchLedgerByExternalId({
+  createdAtGt: new Date("2021-07-28T22:32:03.001Z"),
+  createdAtGte: new Date("2021-10-24T11:02:25.013Z"),
+  createdAtLt: new Date("2023-03-21T02:37:36.068Z"),
+  createdAtLte: new Date("2022-05-04T02:33:27.807Z"),
+  currency: "Pound Sterling",
+  cursor: "OCR back",
+  entryStatus: FetchCustomerCreditsLedgerExternalIdEntryStatusEntryStatus.Pending,
+  entryType: FetchCustomerCreditsLedgerExternalIdEntryTypeEntryType.ExpirationChange,
+  externalCustomerId: "Account",
+  limit: 672484,
+  minimumAmount: "Account Assimilated transition",
+}).then((res: FetchCustomerCreditsLedgerExternalIdResponse) => {
+  if (res.statusCode == 200) {
+    // handle response
+  }
+});
+```
+
+### Parameters
+
+| Parameter                                                                                                                        | Type                                                                                                                             | Required                                                                                                                         | Description                                                                                                                      |
+| -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `request`                                                                                                                        | [operations.FetchCustomerCreditsLedgerExternalIdRequest](../../models/operations/fetchcustomercreditsledgerexternalidrequest.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.FetchCustomerCreditsLedgerExternalIdResponse](../../models/operations/fetchcustomercreditsledgerexternalidresponse.md)>**
+