Customers

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

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": "[email protected]",
    "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.

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.

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.

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:

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.

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.

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.

See Credits and the ledger for what each balance means.

Run customer operations

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
• Credits and the ledger