View Source Stripe.Customer (stripity_stripe v3.2.0)

Retrieve funding instructions for a customer cash balance. If funding instructions do not yet exist for the customer, newfunding instructions will be created. If funding instructions have already been created for a given customer, the same funding instructions will be retrieved. In other words, we will return the same funding instructions each time.

delete(customer, opts \\ [])

Permanently deletes a customer. It cannot be undone. Also immediately cancels any active subscriptions on the customer.

delete_discount(customer, opts \\ [])

Removes the currently applied discount on a customer.

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

Create an incoming testmode bank transfer

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

Returns a list of your customers. The customers are returned sorted by creation date, with the most recent customers appearing first.

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

Returns a list of PaymentMethods for a given Customer

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

Retrieves a Customer object.

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

Retrieves a PaymentMethod object for a given Customer.

search(params \\ %{}, opts \\ [])

Search for customers you’ve previously created using Stripe’s Search Query Language.Don’t use search in read-after-write flows where strict consistency is necessary. Under normal operating conditions, data is searchable in less than a minute. Occasionally, propagation of new or updated data can be up to an hour behind during outages. Search functionality is not available to merchants in India.

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

Updates the specified customer by setting the values of the parameters passed. Any parameters not provided will be left unchanged. For example, if you pass the source parameter, that becomes the customer’s active source (e.g., a card) to be used for all charges in the future. When you update a customer to a new valid card source by passing the source parameter: for each of the customer’s current subscriptions, if the subscription bills automatically and is in the past_due state, then the latest open invoice for the subscription with automatic collection enabled will be retried. This retry will not count as an automatic retry, and will not affect the next regularly scheduled payment for the invoice. Changing the default_source for a customer will not trigger this behavior.

Types

address()

@type address() :: %{
  optional(:city) => binary(),
  optional(:country) => binary(),
  optional(:line1) => binary(),
  optional(:line2) => binary(),
  optional(:postal_code) => binary(),
  optional(:state) => binary()
}

bank_transfer()

@type bank_transfer() :: %{
  optional(:eu_bank_transfer) => eu_bank_transfer(),
  optional(:requested_address_types) => [:iban | :sort_code | :spei | :zengin],
  optional(:type) =>
    :eu_bank_transfer
    | :gb_bank_transfer
    | :jp_bank_transfer
    | :mx_bank_transfer
    | :us_bank_transfer
}

Additional parameters for bank_transfer funding types

cash_balance()

@type cash_balance() :: %{optional(:settings) => settings()}

Balance information and default balance settings for this customer.

created()

@type created() :: %{
  optional(:gt) => integer(),
  optional(:gte) => integer(),
  optional(:lt) => integer(),
  optional(:lte) => integer()
}

custom_fields()

@type custom_fields() :: %{optional(:name) => binary(), optional(:value) => binary()}

eu_bank_transfer()

@type eu_bank_transfer() :: %{optional(:country) => binary()}

Configuration for eu_bank_transfer funding type.

invoice_settings()

@type invoice_settings() :: %{
  optional(:custom_fields) => [custom_fields()] | binary(),
  optional(:default_payment_method) => binary(),
  optional(:footer) => binary(),
  optional(:rendering_options) => rendering_options() | binary()
}

Default invoice settings for this customer.

rendering_options()

@type rendering_options() :: %{
  optional(:amount_tax_display) => :exclude_tax | :include_inclusive_tax
}

settings()

@type settings() :: %{
  optional(:reconciliation_mode) => :automatic | :manual | :merchant_default
}

Settings controlling the behavior of the customer's cash balance, such as reconciliation of funds received.

shipping()

@type shipping() :: %{
  optional(:address) => address(),
  optional(:name) => binary(),
  optional(:phone) => binary()
}

t()

@type t() :: %Stripe.Customer{
  address: term() | nil,
  balance: integer(),
  cash_balance: Stripe.CashBalance.t() | nil,
  created: integer(),
  currency: binary() | nil,
  default_source: (binary() | Stripe.PaymentSource.t()) | nil,
  delinquent: boolean() | nil,
  description: binary() | nil,
  discount: term() | nil,
  email: binary() | nil,
  id: binary(),
  invoice_credit_balance: term(),
  invoice_prefix: binary() | nil,
  invoice_settings: term(),
  livemode: boolean(),
  metadata: term(),
  name: binary() | nil,
  next_invoice_sequence: integer(),
  object: binary(),
  phone: binary() | nil,
  preferred_locales: term() | nil,
  shipping: term() | nil,
  sources: term(),
  subscriptions: term(),
  tax: term(),
  tax_exempt: binary() | nil,
  tax_ids: term(),
  test_clock: (binary() | Stripe.TestHelpers.TestClock.t()) | nil
}

The customer type.

address The customer's address.
balance The current balance, if any, that's stored on the customer. If negative, the customer has credit to apply to their next invoice. If positive, the customer has an amount owed that's added to their next invoice. The balance only considers amounts that Stripe hasn't successfully applied to any invoice. It doesn't reflect unpaid invoices. This balance is only taken into account after invoices finalize.
cash_balance The current funds being held by Stripe on behalf of the customer. You can apply these funds towards payment intents when the source is "cash_balance". The settings[reconciliation_mode] field describes if these funds apply to these payment intents manually or automatically.
created Time at which the object was created. Measured in seconds since the Unix epoch.
currency Three-letter ISO code for the currency the customer can be charged in for recurring billing purposes.
default_source ID of the default payment source for the customer.

If you use payment methods created through the PaymentMethods API, see the invoice_settings.default_payment_method field instead.

delinquent Tracks the most recent state change on any invoice belonging to the customer. Paying an invoice or marking it uncollectible via the API will set this field to false. An automatic payment failure or passing the invoice.due_date will set this field to true.

If an invoice becomes uncollectible by dunning, delinquent doesn't reset to false.

If you care whether the customer has paid their most recent subscription invoice, use subscription.status instead. Paying or marking uncollectible any customer invoice regardless of whether it is the latest invoice for a subscription will always set this field to false.

description An arbitrary string attached to the object. Often useful for displaying to users.
discount Describes the current discount active on the customer, if there is one.
email The customer's email address.
id Unique identifier for the object.
invoice_credit_balance The current multi-currency balances, if any, that's stored on the customer. If positive in a currency, the customer has a credit to apply to their next invoice denominated in that currency. If negative, the customer has an amount owed that's added to their next invoice denominated in that currency. These balances don't apply to unpaid invoices. They solely track amounts that Stripe hasn't successfully applied to any invoice. Stripe only applies a balance in a specific currency to an invoice after that invoice (which is in the same currency) finalizes.
invoice_prefix The prefix for the customer used to generate unique invoice numbers.
invoice_settings
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.
name The customer's full name or business name.
next_invoice_sequence The suffix of the customer's next invoice number (for example, 0001).
object String representing the object's type. Objects of the same type share the same value.
phone The customer's phone number.
preferred_locales The customer's preferred locales (languages), ordered by preference.
shipping Mailing and shipping address for the customer. Appears on invoices emailed to this customer.
sources The customer's payment sources, if any.
subscriptions The customer's current subscriptions, if any.
tax
tax_exempt Describes the customer's tax exemption status, which is none, exempt, or reverse. When set to reverse, invoice and receipt PDFs include the following text: "Reverse charge".
tax_ids The customer's tax IDs.
test_clock ID of the test clock that this customer belongs to.

tax()

@type tax() :: %{
  optional(:ip_address) => binary() | binary(),
  optional(:validate_location) => :deferred | :immediately
}

Tax details about the customer.

tax_id_data()

@type tax_id_data() :: %{
  optional(:type) =>
    :ad_nrt
    | :ae_trn
    | :ar_cuit
    | :au_abn
    | :au_arn
    | :bg_uic
    | :bo_tin
    | :br_cnpj
    | :br_cpf
    | :ca_bn
    | :ca_gst_hst
    | :ca_pst_bc
    | :ca_pst_mb
    | :ca_pst_sk
    | :ca_qst
    | :ch_vat
    | :cl_tin
    | :cn_tin
    | :co_nit
    | :cr_tin
    | :do_rcn
    | :ec_ruc
    | :eg_tin
    | :es_cif
    | :eu_oss_vat
    | :eu_vat
    | :gb_vat
    | :ge_vat
    | :hk_br
    | :hu_tin
    | :id_npwp
    | :il_vat
    | :in_gst
    | :is_vat
    | :jp_cn
    | :jp_rn
    | :jp_trn
    | :ke_pin
    | :kr_brn
    | :li_uid
    | :mx_rfc
    | :my_frp
    | :my_itn
    | :my_sst
    | :no_vat
    | :nz_gst
    | :pe_ruc
    | :ph_tin
    | :ro_tin
    | :rs_pib
    | :ru_inn
    | :ru_kpp
    | :sa_vat
    | :sg_gst
    | :sg_uen
    | :si_tin
    | :sv_nit
    | :th_vat
    | :tr_tin
    | :tw_vat
    | :ua_vat
    | :us_ein
    | :uy_ruc
    | :ve_rif
    | :vn_tin
    | :za_vat,
  optional(:value) => binary()
}

Functions

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

@spec balance_transactions(
  customer :: binary(),
  params :: %{
    optional(:ending_before) => binary(),
    optional(:expand) => [binary()],
    optional(:limit) => integer(),
    optional(:starting_after) => binary()
  },
  opts :: Keyword.t()
) ::
  {:ok, Stripe.List.t(Stripe.CustomerBalanceTransaction.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

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

@spec create(
  params :: %{
    optional(:address) => address() | binary(),
    optional(:balance) => integer(),
    optional(:cash_balance) => cash_balance(),
    optional(:coupon) => binary(),
    optional(:description) => binary(),
    optional(:email) => binary(),
    optional(:expand) => [binary()],
    optional(:invoice_prefix) => binary(),
    optional(:invoice_settings) => invoice_settings(),
    optional(:metadata) => %{optional(binary()) => binary()} | binary(),
    optional(:name) => binary(),
    optional(:next_invoice_sequence) => integer(),
    optional(:payment_method) => binary(),
    optional(:phone) => binary(),
    optional(:preferred_locales) => [binary()],
    optional(:promotion_code) => binary(),
    optional(:shipping) => shipping() | binary(),
    optional(:source) => binary(),
    optional(:tax) => tax(),
    optional(:tax_exempt) => :exempt | :none | :reverse,
    optional(:tax_id_data) => [tax_id_data()],
    optional(:test_clock) => binary(),
    optional(:validate) => boolean()
  },
  opts :: Keyword.t()
) :: {:ok, t()} | {:error, Stripe.ApiErrors.t()} | {:error, term()}

Creates a new customer object.

Details

Method: post
Path: /v1/customers

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

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

#### Details * Method: `post` * Path: `/v1/customers/{customer}/funding_instructions`

delete(customer, opts \\ [])

@spec delete(customer :: binary(), opts :: Keyword.t()) ::
  {:ok, Stripe.DeletedCustomer.t()}
  | {:error, Stripe.ApiErrors.t()}
  | {:error, term()}

Permanently deletes a customer. It cannot be undone. Also immediately cancels any active subscriptions on the customer.

Details

Method: delete
Path: /v1/customers/{customer}

delete_discount(customer, opts \\ [])

@spec delete_discount(customer :: binary(), opts :: Keyword.t()) ::
  {:ok, Stripe.DeletedDiscount.t()}
  | {:error, Stripe.ApiErrors.t()}
  | {:error, term()}

Removes the currently applied discount on a customer.

Details

Method: delete
Path: /v1/customers/{customer}/discount

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

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

Create an incoming testmode bank transfer

Details

Method: post
Path: /v1/test_helpers/customers/{customer}/fund_cash_balance

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

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

Returns a list of your customers. The customers are returned sorted by creation date, with the most recent customers appearing first.

Details

Method: get
Path: /v1/customers

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

@spec list_payment_methods(
  customer :: binary(),
  params :: %{
    optional(:ending_before) => binary(),
    optional(:expand) => [binary()],
    optional(:limit) => integer(),
    optional(:starting_after) => binary(),
    optional(:type) =>
      :acss_debit
      | :affirm
      | :afterpay_clearpay
      | :alipay
      | :au_becs_debit
      | :bacs_debit
      | :bancontact
      | :blik
      | :boleto
      | :card
      | :cashapp
      | :customer_balance
      | :eps
      | :fpx
      | :giropay
      | :grabpay
      | :ideal
      | :klarna
      | :konbini
      | :link
      | :oxxo
      | :p24
      | :paynow
      | :paypal
      | :pix
      | :promptpay
      | :revolut_pay
      | :sepa_debit
      | :sofort
      | :us_bank_account
      | :wechat_pay
      | :zip
  },
  opts :: Keyword.t()
) ::
  {:ok, Stripe.List.t(Stripe.PaymentMethod.t())}
  | {:error, Stripe.ApiErrors.t()}
  | {:error, term()}

Returns a list of PaymentMethods for a given Customer

Details

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

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

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

Retrieves a Customer object.

Details

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

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

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

Retrieves a PaymentMethod object for a given Customer.

Details

Method: get
Path: /v1/customers/{customer}/payment_methods/{payment_method}

search(params \\ %{}, opts \\ [])

@spec search(
  params :: %{
    optional(:expand) => [binary()],
    optional(:limit) => integer(),
    optional(:page) => binary(),
    optional(:query) => binary()
  },
  opts :: Keyword.t()
) ::
  {:ok, Stripe.SearchResult.t(t())}
  | {:error, Stripe.ApiErrors.t()}
  | {:error, term()}

#### Details * Method: `get` * Path: `/v1/customers/search`

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

@spec update(
  customer :: binary(),
  params :: %{
    optional(:address) => address() | binary(),
    optional(:balance) => integer(),
    optional(:cash_balance) => cash_balance(),
    optional(:coupon) => binary(),
    optional(:default_source) => binary(),
    optional(:description) => binary(),
    optional(:email) => binary(),
    optional(:expand) => [binary()],
    optional(:invoice_prefix) => binary(),
    optional(:invoice_settings) => invoice_settings(),
    optional(:metadata) => %{optional(binary()) => binary()} | binary(),
    optional(:name) => binary(),
    optional(:next_invoice_sequence) => integer(),
    optional(:phone) => binary(),
    optional(:preferred_locales) => [binary()],
    optional(:promotion_code) => binary(),
    optional(:shipping) => shipping() | binary(),
    optional(:source) => binary(),
    optional(:tax) => tax(),
    optional(:tax_exempt) => :exempt | :none | :reverse,
    optional(:validate) => boolean()
  },
  opts :: Keyword.t()
) :: {:ok, t()} | {:error, Stripe.ApiErrors.t()} | {:error, term()}

This request accepts mostly the same arguments as the customer creation call.

Details

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