# `MishkaPay.Customer`
[🔗](https://github.com/mishka-group/mishka_pay/blob/v0.0.1/lib/mishka_pay/customer.ex#L5)

A buyer the provider keeps: who they are, so a returning buyer pays without typing their details
again and their payments, invoices and subscriptions hang off one record. A guarded_struct.

At Stripe a customer is an account with the customer configuration (Accounts v2, `acct_...`, the
default) or a Customer (`/v1/customers`, `cus_...`), as the call's `:api` or the tenant's
`:customer_api` (`MishkaPay.Credentials`) says. Every call that takes a customer id takes
either kind.

Made with `MishkaPay.create_customer/1`, changed with `MishkaPay.update_customer/1`, read with
`MishkaPay.fetch_customer/3` and `MishkaPay.list_customers/3`. A host keeps the customer's `:id`
on its own user or account.

What the caller gives:

  * `:provider`, `:tenant`: which provider, with whose keys.
  * `:api`: which of the provider's APIs makes it, `:v2` or `:v1` (Stripe's Accounts v2 or its
    Customers); left out, the tenant's `:customer_api` setting (`:v2` by default). A read
    answers the API it was read with: a customer is read, changed and deleted with the API its
    id belongs to.
  * `:email`, `:name`, `:phone`: the buyer's details.
  * `:address`: where the buyer lives, a `MishkaPay.Address` (their billing address).
  * `:default_payment_method`: the payment method future invoices are paid with (`pm_...`),
    one the customer already keeps.
  * `:reference`: the host's own id for the buyer (a user id); it makes the idempotency key, so
    the same reference never makes two customers, and it comes back on the customer.
  * `:metadata`: extra pairs, string keys to string values.

What the provider fills in: `:id`, `:created_at`.

In a checkout, `customer: %{id: "acct_..."}` (or `"cus_..."`) sells to a known customer and
`customer: %{email: "..."}` fills in the email for a new buyer: one or the other
(`MishkaPay.Checkout`).

# `t`

```elixir
@type t() :: %MishkaPay.Customer{
  address: MishkaPay.Address.t() | nil,
  api: (:v2 | :v1) | nil,
  balance_transaction: MishkaPay.Customer.BalanceTransaction.t() | nil,
  created_at: DateTime.t() | nil,
  default_payment_method: String.t() | nil,
  email: String.t() | nil,
  id: String.t() | nil,
  metadata: map() | nil,
  name: String.t() | nil,
  payment_method: MishkaPay.Customer.PaymentMethod.t() | nil,
  phone: String.t() | nil,
  provider: String.t() | nil,
  reference: String.t() | nil,
  tax_id: MishkaPay.Customer.TaxId.t() | nil,
  tenant: term() | nil
}
```

The struct that `builder/1` returns.

| Field | Type | Required | Default | Description | Derives |
| --- | --- | --- | --- | --- | --- |
| `:provider` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty)` |
| `:tenant` | `term()` \| `nil` | no |  |  |  |
| `:id` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty)` |
| `:email` | `String.t()` \| `nil` | no |  |  | `sanitize(trim, downcase) validate(string, email_r)` |
| `:name` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty, max_len=250)` |
| `:phone` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty, max_len=30)` |
| `:address` | [`MishkaPay.Address.t()`](`t:MishkaPay.Address.t/0`) \| `nil` | no |  |  |  |
| `:api` | `:v2` \| `:v1` \| `nil` | no |  |  | `validate(enum=Atom[v2::v1])`<br>validator `{MishkaPay.ConnectedAccount, :api}` |
| `:reference` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty, max_len=200)` |
| `:metadata` | `map()` \| `nil` | no | `%{}` |  | `validate(map)`<br>validator `{MishkaPay.Checkout, :metadata}` |
| `:default_payment_method` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:created_at` | `DateTime.t()` \| `nil` | no |  |  | `validate(struct)` |
| `:balance_transaction` | [`MishkaPay.Customer.BalanceTransaction.t()`](`t:MishkaPay.Customer.BalanceTransaction.t/0`) \| `nil` | no |  | One change of a customer's balance at the provider: store credit given, a debit added, or credit used on a bill. Made with `MishkaPay.adjust_customer_balance/5` and listed with `MishkaPay.list_customer_balance/4`. A guarded_struct. |  |
| `:tax_id` | [`MishkaPay.Customer.TaxId.t()`](`t:MishkaPay.Customer.TaxId.t/0`) \| `nil` | no |  | A business buyer's tax id kept on a provider customer (`txi_...` at Stripe), such as an EU VAT number. The provider prints it on the customer's invoices, and a provider that counts the tax (Stripe Tax) may then charge no VAT and note a reverse charge. A guarded_struct. |  |
| `:payment_method` | [`MishkaPay.Customer.PaymentMethod.t()`](`t:MishkaPay.Customer.PaymentMethod.t/0`) \| `nil` | no |  | A payment method a customer saved at the provider (`pm_...` at Stripe), such as a card, so a later invoice or subscription charges it without the buyer typing it again. A guarded_struct the provider fills in. |  |

# `builder`

# `enforce_keys`

# `enforce_keys`

# `example`

A sample %MishkaPay.Customer{} populated from defaults + type-based fallbacks.

# `keys`

# `keys`

---

*Consult [api-reference.md](api-reference.md) for complete listing*
