---
title: "List customers"
canonical_url: "https://twominutebilling.com/help/developers/api-reference/customers/list-customers"
---
# List customers

<api-operation method="GET" path="/v1/businesses/{biz}/customers">
<template v-slot:docs="">

## Path parameters

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        biz
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <strong>
        yes
      </strong>
    </td>
    
    <td>
      Business id (biz_…)
    </td>
  </tr>
</tbody>
</table>

## Response

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The object type; always <code>
        list
      </code>
      
      . One of <code>
        list
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data
      </code>
    </td>
    
    <td>
      <code>
        array of object
      </code>
    </td>
    
    <td>
      The rows on this page.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.credit_settings
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      Credit policy for this customer: an override of what happens when credit is used up (ignored after <code>
        override_expires_at
      </code>
      
      ), and an overdraft limit per currency. Replaced whole; null = the business's settings.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.object
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The object type.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.id
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The customer's id (cus_…).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.email
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The customer's email address.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.name
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      DERIVED, read-only (deprecated 2026-08-23): <code>
        first_name last_name
      </code>
      
      , else <code>
        company
      </code>
      
      , else null. There is no <code>
        customer.name
      </code>
      
       any more — sending this field to create or update returns 400. It is emitted only so a caller has a flat display string. Two distinct identities exist and neither is derived from the other: <code>
        first_name
      </code>
      
      /<code>
        last_name
      </code>
      
      /<code>
        company
      </code>
      
       are the ACCOUNT HOLDER (lists, emails, portal greeting), while <code>
        address.first_name
      </code>
      
      /<code>
        last_name
      </code>
      
      /<code>
        company
      </code>
      
       are the BILLING CONTACT, which is what gets printed on invoices and credit notes and sent to the gateway as the billing name.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.currency
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The currency the operator pinned on the customer, if any. Prefer effective_currency when deciding what to transact in.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.effective_currency
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      DERIVED, read-only: the currency to transact in — <code>
        currency
      </code>
      
       when the operator set one, else the currency of the customer's live (active/in_trial) subscriptions, highest MRR winning a tie. Emitted by GET (detail) and by the list; absent from create/patch/archive responses. Null when there is nothing to derive from — fall back to the business default. Never write it back to <code>
        currency
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.lifetime_revenue
      </code>
    </td>
    
    <td>
      <code>
        array of object
      </code>
    </td>
    
    <td>
      DERIVED, read-only: cash collected from this customer, one entry per currency — succeeded payments minus succeeded refunds. Credits applied to invoices are not cash and are excluded. Emitted by GET (detail) only.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.tax_exempt
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      True if the customer is exempt from tax.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.email_notifications
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      Whether the customer gets billing emails.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.marketing_opt_in
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      The customer's answer to the marketing opt-in at checkout. Null when they were never asked.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.marketing_opt_in_at
      </code>
    </td>
    
    <td>
      <code>
        string · ISO-8601
      </code>
    </td>
    
    <td>
      The marketing opt in time (ISO-8601 UTC).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.dunning_excluded
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      True if the customer is excluded from dunning.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.exclude_from_reporting
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      True if the customer is left out of metrics and reports.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.billing_cc_emails
      </code>
    </td>
    
    <td>
      <code>
        array of string
      </code>
    </td>
    
    <td>
      Addresses copied on the customer's invoice and receipt emails.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.billing_bcc_emails
      </code>
    </td>
    
    <td>
      <code>
        array of string
      </code>
    </td>
    
    <td>
      Addresses blind-copied on the customer's invoice and receipt emails.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.tax_behavior
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Whether every taxed line for this customer is inclusive or exclusive. Null = each price decides. One of <code>
        inclusive
      </code>
      
      , <code>
        exclusive
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.dunning_policy
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The customer's dunning policy.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.vat_number
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The customer's VAT number.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.withholding_rate_bps
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      The withholding rate on the customer's payments, in basis points (100 = 1%).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.custom_fields
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      Stored custom-field values; also flattened onto the object as cf_<name>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        has_more
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      Whether more rows exist after this page.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        next_cursor
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Opaque; pass as starting_after
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        next_offset
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Present only while has_more; the same opaque token as next_cursor — pass as offset
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        total
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      Filtered-set count; first page only
    </td>
  </tr>
</tbody>
</table>

## Status codes

<table>
<thead>
  <tr>
    <th>
      Status
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        200
      </code>
    </td>
    
    <td>
      Success
    </td>
  </tr>
</tbody>
</table>
</template>

<template v-slot:request="">

```bash [Request]
curl "$TMBILLING_URL/v1/businesses/biz_XXXXXXXXXXXX01/customers" \
  -H "Authorization: Bearer $TMBILLING_API_KEY"
```

</template>

<template v-slot:response="">

```json [200 OK]
{
  "object": "list",
  "data": [
    {
      "object": "customer",
      "id": "cus_XXXXXXXXXXXX01",
      "email": "maya@example.com",
      "name": "Maya Castillo"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "next_offset": "eyJvZmZzZXQiOjEwfQ",
  "total": 2900
}
```

</template>
</api-operation>


## Sitemap

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