orb-billing 0.1.0.pre.alpha.37 → 0.1.0.pre.alpha.39

data/rbi/lib/orb/resources/customers/credits/ledger.rbi

@@ -6,86 +6,86 @@ module Orb
       class Credits
         class Ledger
           # 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](/api-reference/pagination) lists these
-          #   entries, starting from the most recent ledger entry.
+          # with a list of actions that have taken place to modify a customer's credit
+          # balance. This [paginated endpoint](/api-reference/pagination) lists these
+          # entries, starting from the most recent ledger entry.
           #
-          #   More details on using Orb's real-time credit feature are
-          #   [here](/product-catalog/prepurchase).
+          # More details on using Orb's real-time credit feature are
+          # [here](/product-catalog/prepurchase).
           #
-          #   There are four major types of modifications to credit balance, detailed below.
+          # There are four major types of modifications to credit balance, detailed below.
           #
-          #   ## Increment
+          # ## 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.
+          # 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
+          # ## 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.
+          # 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.
+          # 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.
+          # 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 (e.g. trial credits with a $0 cost
-          #   basis before paid credits with a $5.00 cost basis).
+          # If there are multiple blocks with the same expiration date, Orb will deduct from
+          # the block with the _lower cost basis_ first (e.g. 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.
+          # 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
+          # ## 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.
+          # 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
+          # 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
+          # ## 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.
+          # 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
+          # ## 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.
+          # 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
+          # ## 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.
+          # 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
+          # ## 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.
+          # 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.
           sig do
             params(
               customer_id: String,
@@ -103,15 +103,15 @@ module Orb
             )
               .returns(
                 Orb::Internal::Page[
-                T.any(
-                  Orb::Models::Customers::Credits::LedgerListResponse::IncrementLedgerEntry,
-                  Orb::Models::Customers::Credits::LedgerListResponse::DecrementLedgerEntry,
-                  Orb::Models::Customers::Credits::LedgerListResponse::ExpirationChangeLedgerEntry,
-                  Orb::Models::Customers::Credits::LedgerListResponse::CreditBlockExpiryLedgerEntry,
-                  Orb::Models::Customers::Credits::LedgerListResponse::VoidLedgerEntry,
-                  Orb::Models::Customers::Credits::LedgerListResponse::VoidInitiatedLedgerEntry,
-                  Orb::Models::Customers::Credits::LedgerListResponse::AmendmentLedgerEntry
-                )
+                  T.any(
+                    Orb::Models::Customers::Credits::LedgerListResponse::IncrementLedgerEntry,
+                    Orb::Models::Customers::Credits::LedgerListResponse::DecrementLedgerEntry,
+                    Orb::Models::Customers::Credits::LedgerListResponse::ExpirationChangeLedgerEntry,
+                    Orb::Models::Customers::Credits::LedgerListResponse::CreditBlockExpiryLedgerEntry,
+                    Orb::Models::Customers::Credits::LedgerListResponse::VoidLedgerEntry,
+                    Orb::Models::Customers::Credits::LedgerListResponse::VoidInitiatedLedgerEntry,
+                    Orb::Models::Customers::Credits::LedgerListResponse::AmendmentLedgerEntry
+                  )
                 ]
               )
           end
@@ -124,7 +124,7 @@ module Orb
             # The ledger currency or custom pricing unit to use.
             currency: nil,
             # Cursor for pagination. This can be populated by the `next_cursor` value returned
-            #   from the initial request.
+            # from the initial request.
             cursor: nil,
             entry_status: nil,
             entry_type: nil,
@@ -132,119 +132,117 @@ module Orb
             limit: nil,
             minimum_amount: nil,
             request_options: {}
-          )
-          end
-
+          ); end
           # 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-ledger) 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.
+          # 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-ledger) 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.
           sig do
             params(
               customer_id: String,
@@ -279,155 +277,153 @@ module Orb
           def create_entry(
             customer_id,
             # The number of credits to effect. Note that this is required for increment,
-            #   decrement or void operations.
+            # decrement or void operations.
             amount:,
             entry_type:,
             # An ISO 8601 format date that identifies the origination credit block to expire
             expiry_date:,
             # A future date (specified in YYYY-MM-DD format) used for expiration change,
-            #   denoting when credits transferred (as part of a partial block expiration) should
-            #   expire.
+            # denoting when credits transferred (as part of a partial block expiration) should
+            # expire.
             target_expiry_date:,
             # The ID of the block to reverse a decrement from.
             block_id:,
             # The currency or custom pricing unit to use for this ledger entry. If this is a
-            #   real-world currency, it must match the customer's invoicing currency.
+            # real-world currency, it must match the customer's invoicing currency.
             currency: nil,
             # Optional metadata that can be specified when adding ledger results via the API.
-            #   For example, this can be used to note an increment refers to trial credits, or
-            #   for noting corrections as a result of an incident, etc.
+            # For example, this can be used to note an increment refers to trial credits, or
+            # for noting corrections as a result of an incident, etc.
             description: nil,
             # An ISO 8601 format date that denotes when this credit balance should become
-            #   available for use.
+            # available for use.
             effective_date: nil,
             # Passing `invoice_settings` automatically generates an invoice for the newly
-            #   added credits. If `invoice_settings` is passed, you must specify
-            #   per_unit_cost_basis, as the calculation of the invoice total is done on that
-            #   basis.
+            # added credits. If `invoice_settings` is passed, you must specify
+            # per_unit_cost_basis, as the calculation of the invoice total is done on that
+            # basis.
             invoice_settings: nil,
             # User-specified key/value pairs for the resource. Individual keys can be removed
-            #   by setting the value to `null`, and the entire metadata mapping can be cleared
-            #   by setting `metadata` to `null`.
+            # by setting the value to `null`, and the entire metadata mapping can be cleared
+            # by setting `metadata` to `null`.
             metadata: nil,
             # Can only be specified when entry_type=increment. How much, in the customer's
-            #   currency, a customer paid for a single credit in this block
+            # currency, a customer paid for a single credit in this block
             per_unit_cost_basis: nil,
             # Can only be specified when `entry_type=void`. The reason for the void.
             void_reason: nil,
             request_options: {}
-          )
-          end
-
+          ); end
           # 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-ledger) 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.
+          # 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-ledger) 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.
           sig do
             params(
               external_customer_id: String,
@@ -465,126 +461,124 @@ module Orb
           def create_entry_by_external_id(
             external_customer_id,
             # The number of credits to effect. Note that this is required for increment,
-            #   decrement or void operations.
+            # decrement or void operations.
             amount:,
             entry_type:,
             # An ISO 8601 format date that identifies the origination credit block to expire
             expiry_date:,
             # A future date (specified in YYYY-MM-DD format) used for expiration change,
-            #   denoting when credits transferred (as part of a partial block expiration) should
-            #   expire.
+            # denoting when credits transferred (as part of a partial block expiration) should
+            # expire.
             target_expiry_date:,
             # The ID of the block to reverse a decrement from.
             block_id:,
             # The currency or custom pricing unit to use for this ledger entry. If this is a
-            #   real-world currency, it must match the customer's invoicing currency.
+            # real-world currency, it must match the customer's invoicing currency.
             currency: nil,
             # Optional metadata that can be specified when adding ledger results via the API.
-            #   For example, this can be used to note an increment refers to trial credits, or
-            #   for noting corrections as a result of an incident, etc.
+            # For example, this can be used to note an increment refers to trial credits, or
+            # for noting corrections as a result of an incident, etc.
             description: nil,
             # An ISO 8601 format date that denotes when this credit balance should become
-            #   available for use.
+            # available for use.
             effective_date: nil,
             # Passing `invoice_settings` automatically generates an invoice for the newly
-            #   added credits. If `invoice_settings` is passed, you must specify
-            #   per_unit_cost_basis, as the calculation of the invoice total is done on that
-            #   basis.
+            # added credits. If `invoice_settings` is passed, you must specify
+            # per_unit_cost_basis, as the calculation of the invoice total is done on that
+            # basis.
             invoice_settings: nil,
             # User-specified key/value pairs for the resource. Individual keys can be removed
-            #   by setting the value to `null`, and the entire metadata mapping can be cleared
-            #   by setting `metadata` to `null`.
+            # by setting the value to `null`, and the entire metadata mapping can be cleared
+            # by setting `metadata` to `null`.
             metadata: nil,
             # Can only be specified when entry_type=increment. How much, in the customer's
-            #   currency, a customer paid for a single credit in this block
+            # currency, a customer paid for a single credit in this block
             per_unit_cost_basis: nil,
             # Can only be specified when `entry_type=void`. The reason for the void.
             void_reason: nil,
             request_options: {}
-          )
-          end
-
+          ); end
           # 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](/api-reference/pagination) lists these
-          #   entries, starting from the most recent ledger entry.
+          # with a list of actions that have taken place to modify a customer's credit
+          # balance. This [paginated endpoint](/api-reference/pagination) lists these
+          # entries, starting from the most recent ledger entry.
           #
-          #   More details on using Orb's real-time credit feature are
-          #   [here](/product-catalog/prepurchase).
+          # More details on using Orb's real-time credit feature are
+          # [here](/product-catalog/prepurchase).
           #
-          #   There are four major types of modifications to credit balance, detailed below.
+          # There are four major types of modifications to credit balance, detailed below.
           #
-          #   ## Increment
+          # ## 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.
+          # 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
+          # ## 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.
+          # 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.
+          # 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.
+          # 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 (e.g. trial credits with a $0 cost
-          #   basis before paid credits with a $5.00 cost basis).
+          # If there are multiple blocks with the same expiration date, Orb will deduct from
+          # the block with the _lower cost basis_ first (e.g. 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.
+          # 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
+          # ## 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.
+          # 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
+          # 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
+          # ## 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.
+          # 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
+          # ## 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.
+          # 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
+          # ## 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.
+          # 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
+          # ## 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.
+          # 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.
           sig do
             params(
               external_customer_id: String,
@@ -602,15 +596,15 @@ module Orb
             )
               .returns(
                 Orb::Internal::Page[
-                T.any(
-                  Orb::Models::Customers::Credits::LedgerListByExternalIDResponse::IncrementLedgerEntry,
-                  Orb::Models::Customers::Credits::LedgerListByExternalIDResponse::DecrementLedgerEntry,
-                  Orb::Models::Customers::Credits::LedgerListByExternalIDResponse::ExpirationChangeLedgerEntry,
-                  Orb::Models::Customers::Credits::LedgerListByExternalIDResponse::CreditBlockExpiryLedgerEntry,
-                  Orb::Models::Customers::Credits::LedgerListByExternalIDResponse::VoidLedgerEntry,
-                  Orb::Models::Customers::Credits::LedgerListByExternalIDResponse::VoidInitiatedLedgerEntry,
-                  Orb::Models::Customers::Credits::LedgerListByExternalIDResponse::AmendmentLedgerEntry
-                )
+                  T.any(
+                    Orb::Models::Customers::Credits::LedgerListByExternalIDResponse::IncrementLedgerEntry,
+                    Orb::Models::Customers::Credits::LedgerListByExternalIDResponse::DecrementLedgerEntry,
+                    Orb::Models::Customers::Credits::LedgerListByExternalIDResponse::ExpirationChangeLedgerEntry,
+                    Orb::Models::Customers::Credits::LedgerListByExternalIDResponse::CreditBlockExpiryLedgerEntry,
+                    Orb::Models::Customers::Credits::LedgerListByExternalIDResponse::VoidLedgerEntry,
+                    Orb::Models::Customers::Credits::LedgerListByExternalIDResponse::VoidInitiatedLedgerEntry,
+                    Orb::Models::Customers::Credits::LedgerListByExternalIDResponse::AmendmentLedgerEntry
+                  )
                 ]
               )
           end
@@ -623,7 +617,7 @@ module Orb
             # The ledger currency or custom pricing unit to use.
             currency: nil,
             # Cursor for pagination. This can be populated by the `next_cursor` value returned
-            #   from the initial request.
+            # from the initial request.
             cursor: nil,
             entry_status: nil,
             entry_type: nil,
@@ -631,13 +625,10 @@ module Orb
             limit: nil,
             minimum_amount: nil,
             request_options: {}
-          )
-          end
-
+          ); end
           # @api private
           sig { params(client: Orb::Client).returns(T.attached_class) }
-          def self.new(client:)
-          end
+          def self.new(client:); end
         end
       end
     end