View Source Stripe.CustomerBalanceTransaction (stripity_stripe v3.2.0)

Each customer has a Balance value, which denotes a debit or credit that's automatically applied to their next invoice upon finalization. You may modify the value directly by using the update customer API, or by creating a Customer Balance Transaction, which increments or decrements the customer's balance by the specified amount.

Related guide: Customer balance

Summary

Types

t()

The customer_balance_transaction type.

Functions

create(customer, params \\ %{}, opts \\ [])

Creates an immutable transaction that updates the customer’s credit balance.

list(customer, params \\ %{}, opts \\ [])

Returns a list of transactions that updated the customer’s balances.

retrieve(customer, transaction, params \\ %{}, opts \\ [])

Retrieves a specific customer balance transaction that updated the customer’s balances.

update(customer, transaction, params \\ %{}, opts \\ [])

Most credit balance transaction fields are immutable, but you may update its description and metadata.

Types

t()

@type t() :: %Stripe.CustomerBalanceTransaction{
  amount: integer(),
  created: integer(),
  credit_note: (binary() | Stripe.CreditNote.t()) | nil,
  currency: binary(),
  customer: binary() | Stripe.Customer.t(),
  description: binary() | nil,
  ending_balance: integer(),
  id: binary(),
  invoice: (binary() | Stripe.Invoice.t()) | nil,
  livemode: boolean(),
  metadata: term() | nil,
  object: binary(),
  type: binary()
}

The customer_balance_transaction type.

amount The amount of the transaction. A negative value is a credit for the customer's balance, and a positive value is a debit to the customer's balance.
created Time at which the object was created. Measured in seconds since the Unix epoch.
credit_note The ID of the credit note (if any) related to the transaction.
currency Three-letter ISO currency code, in lowercase. Must be a supported currency.
customer The ID of the customer the transaction belongs to.
description An arbitrary string attached to the object. Often useful for displaying to users.
ending_balance The customer's balance after the transaction was applied. A negative value decreases the amount due on the customer's next invoice. A positive value increases the amount due on the customer's next invoice.
id Unique identifier for the object.
invoice The ID of the invoice (if any) related to the transaction.
livemode Has the value true if the object exists in live mode or the value false if the object exists in test mode.
metadata Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
object String representing the object's type. Objects of the same type share the same value.
type Transaction type: adjustment, applied_to_invoice, credit_note, initial, invoice_overpaid, invoice_too_large, invoice_too_small, unspent_receiver_credit, or unapplied_from_invoice. See the Customer Balance page to learn more about transaction types.

Functions

create(customer, params \\ %{}, opts \\ [])

@spec create(
  customer :: binary(),
  params :: %{
    optional(:amount) => integer(),
    optional(:currency) => binary(),
    optional(:description) => binary(),
    optional(:expand) => [binary()],
    optional(:metadata) => %{optional(binary()) => binary()} | binary()
  },
  opts :: Keyword.t()
) :: {:ok, t()} | {:error, Stripe.ApiErrors.t()} | {:error, term()}

Creates an immutable transaction that updates the customer’s credit balance.

Details

Method: post
Path: /v1/customers/{customer}/balance_transactions

list(customer, params \\ %{}, opts \\ [])

@spec list(
  customer :: binary(),
  params :: %{
    optional(:ending_before) => binary(),
    optional(:expand) => [binary()],
    optional(:limit) => integer(),
    optional(:starting_after) => binary()
  },
  opts :: Keyword.t()
) ::
  {:ok, Stripe.List.t(t())} | {:error, Stripe.ApiErrors.t()} | {:error, term()}

Returns a list of transactions that updated the customer’s balances.

Details

Method: get
Path: /v1/customers/{customer}/balance_transactions

retrieve(customer, transaction, params \\ %{}, opts \\ [])

@spec retrieve(
  customer :: binary(),
  transaction :: binary(),
  params :: %{optional(:expand) => [binary()]},
  opts :: Keyword.t()
) :: {:ok, t()} | {:error, Stripe.ApiErrors.t()} | {:error, term()}

Retrieves a specific customer balance transaction that updated the customer’s balances.

Details

Method: get
Path: /v1/customers/{customer}/balance_transactions/{transaction}

update(customer, transaction, params \\ %{}, opts \\ [])

@spec update(
  customer :: binary(),
  transaction :: binary(),
  params :: %{
    optional(:description) => binary(),
    optional(:expand) => [binary()],
    optional(:metadata) => %{optional(binary()) => binary()} | binary()
  },
  opts :: Keyword.t()
) :: {:ok, t()} | {:error, Stripe.ApiErrors.t()} | {:error, term()}

Most credit balance transaction fields are immutable, but you may update its description and metadata.

Details

Method: post
Path: /v1/customers/{customer}/balance_transactions/{transaction}