---
title: "The population an unsaved filter set names"
description: "Takes the customer list's own field[op]=value grammar verbatim, so previewing a segment and listing customers are the same request shape."
canonical_url: "https://twominutebilling.com/help/developers/api-reference/customer-segments/the-population-an-unsaved-filter-set-names"
---
# The population an unsaved filter set names

> Takes the customer list's own field[op]=value grammar verbatim, so previewing a segment and listing customers are the same request shape.

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

Takes the customer list's own `field[op]=value` grammar verbatim, so previewing a segment and listing customers are the same request shape. Validated against the same allow-list a saved segment is, so a preview cannot succeed where the save would fail. With no filters it answers for every customer.

## 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>

## Query parameters

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

<tbody>
  <tr>
    <td>
      <code>
        limit
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Maximum number of customers to return.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        starting_after
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Opaque cursor from a previous <code>
        next_cursor
      </code>
      
      .
    </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>
        data.segment_facts
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      Per-customer figures the segment table renders: <code>
        statuses
      </code>
      
       counts subscriptions by API status (so <code>
        non_renewing
      </code>
      
       appears, as it does on the subscriptions list), and <code>
        mrr
      </code>
      
       maps ISO code → integer minor units over the earning ones.
    </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>
      Pass as <code>
        starting_after
      </code>
      
       to get the next page. Null on the last page.
    </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>
      Total number of matching customers.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        segment
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The segment's id (seg_…), or null for a preview.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        mrr_by_currency
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      Total MRR of the matching customers per currency, in minor units.
    </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>
  
  <tr>
    <td>
      <code>
        400
      </code>
    </td>
    
    <td>
      Invalid or refused filter set
    </td>
  </tr>
</tbody>
</table>
</template>

<template v-slot:request="">

```bash [Request]
curl "$TMBILLING_URL/v1/businesses/biz_XXXXXXXXXXXX01/customer_segments/preview?limit=10" \
  -H "Authorization: Bearer $TMBILLING_API_KEY"
```

</template>

<template v-slot:response="">
<code-group>

```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,
  "segment": "seg_XXXXXXXXXXXX01",
  "mrr_by_currency": {}
}
```

```json [400 Bad Request]
{
  "error": {
    "type": "invalid_request_error",
    "message": "Invalid or refused filter set"
  }
}
```

</code-group>
</template>
</api-operation>


## Sitemap

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