---
title: "Customers"
description: "Create the customer who pays, with the currency and address fields that tax depends on, saved payment methods with a backup role, and three separate balances."
canonical_url: "https://twominutebilling.com/help/developers/concepts/customers"
---
# Customers

> Create the customer who pays, with the currency and address fields that tax depends on, saved payment methods with a backup role, and three separate balances.

A customer belongs to one business and pays the bills. Create one with just an email, or with
everything tax and invoicing will need:

```bash
curl -X POST $TMBILLING_URL/v1/businesses/$BIZ/customers \
  -H "Authorization: Bearer $TMBILLING_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "maya@example.com",
    "first_name": "Maya",
    "last_name": "Castillo",
    "company": "Brightwater Analytics",
    "currency": "USD",
    "address": {
      "line1": "12 Dean Street",
      "city": "London",
      "postal_code": "W1D 3RR",
      "country": "GB"
    }
  }'
```

## Set the currency carefully

`currency` fixes what you bill this customer in, and therefore which prices you can put them on.
Subscribe a USD customer to a EUR price and tmbilling refuses the request rather than converting
it. See [Money and currency](https://twominutebilling.com/help/developers/api-essentials/money).

## Fill in the address before the first invoice

`address.country` and its state or province set the place of supply, which decides what tax
applies. `vat_number`, `tax_exempt` and `withholding_rate_bps` change the calculation outright.

Set them before you raise an invoice. tmbilling snapshots them onto each invoice, so correcting an
address later does not re-tax a document it already issued. See [Tax](https://twominutebilling.com/help/developers/concepts/tax).

<endpoint method="POST" path="/v1/businesses/{biz}/customers/{cus}/validate_vat">



</endpoint>

Validates the stored VAT number rather than trusting what someone typed.

## Add contacts

The customer record holds the primary billing identity. Add contacts for the other people who
should receive billing email — an accounts-payable address, a technical owner.

<endpoint method="POST" path="/v1/businesses/{biz}/customers/{cus}/contacts">



</endpoint>

## Attach payment methods

Card details never reach tmbilling. The gateway vaults the instrument and returns a token, and
tmbilling stores that token with the non-secret descriptors — brand, last four, expiry. Your
deployment stays out of PCI scope.

Each payment method carries a status that an expiry sweep keeps current — `valid`, `expiring`,
`expired`, `invalid` or `pending_verification` — and a role:

<table>
<thead>
  <tr>
    <th>
      Role
    </th>
    
    <th>
      When tmbilling charges it
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        primary
      </code>
    </td>
    
    <td>
      First, for every automatic collection.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        backup
      </code>
    </td>
    
    <td>
      When the primary declines for any reason, within the same collection attempt rather than on the next retry: newest first, at most three instruments per run. A customer with a backup card survives an expired primary without entering dunning.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        none
      </code>
    </td>
    
    <td>
      Never, for automatic collection. The card stays on file.
    </td>
  </tr>
</tbody>
</table>

A customer has one primary. Every other card is a backup unless set to `none`, and a newly vaulted
card starts as a backup. Making a card primary moves the previous primary to backup. You cannot demote the primary itself (`409`), so make another card primary instead.

<endpoint method="POST" path="/v1/businesses/{biz}/customers/{cus}/payment_methods/{pm}/assign_role">



</endpoint>

<endpoint method="GET" path="/v1/businesses/{biz}/customers/{cus}/payment_methods">



</endpoint>

To collect a card without your API key reaching your buyer's browser, create a hosted checkout or
customer portal session. See [Hosted checkout and portal](https://twominutebilling.com/help/developers/recipes/checkout-and-portal).

## Read their balances

Each customer holds three separate balances per currency, not one number. tmbilling spends them
in a fixed order, and only some of them are refundable.

<endpoint method="GET" path="/v1/businesses/{biz}/customers/{cus}/wallet">



</endpoint>

See [Credits and the ledger](https://twominutebilling.com/help/developers/concepts/credits) for what each balance means.

## Run customer operations

<table>
<thead>
  <tr>
    <th>
      Call
    </th>
    
    <th>
      What it does
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        POST /customers/{cus}/collect_payment
      </code>
    </td>
    
    <td>
      Charges the customer and pays down their open invoices, booking anything left over as excess credit.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST /customers/{cus}/change_billing_date
      </code>
    </td>
    
    <td>
      Moves this customer's calendar billing date, so you can align all their subscriptions on one invoice day.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST /customers/{cus}/clear_personal_data
      </code>
    </td>
    
    <td>
      Redacts personal data for a GDPR erasure request while leaving the invoices and ledger entries intact.
    </td>
  </tr>
</tbody>
</table>

## Archive a customer

`DELETE` archives a customer rather than deleting them. Their record, invoices and ledger entries
remain, because tmbilling never deletes money that moved. Archiving stops new activity. It does not rewrite history.

## Related

- [Manage customers in the dashboard](https://twominutebilling.com/help/guides/customers-and-subscriptions)
- [Credits and the ledger](https://twominutebilling.com/help/developers/concepts/credits)


## Sitemap

See the full [sitemap](https://twominutebilling.com/sitemap.md) for all pages.