> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tagada.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Customer Management

> Create, list, and manage customers with tags for funnel routing

# Customer Management

The Customers API lets you **create** records, **list** with filters, and **retrieve** by ID. Customer **tags** power funnel segmentation together with device and geo enrichment.

***

## Create a customer

```ts theme={null}
const customer = await tagada.customers.create({
  storeId: 'store_...',
  email: 'jane@example.com',
  firstName: 'Jane',
  lastName: 'Doe',
});
```

***

## List with filters

```ts theme={null}
const { data: customers, total, hasMore } = await tagada.customers.list({
  filters: {
    storeIds: ['store_...'],
    email: 'jane@example.com',
    tags: ['vip'],
  },
  pageSize: 25,
});
```

Supported filters include `storeIds`, `firstName`, `lastName`, `email`, `paymentInstrumentCardLast4`, and `tags`. Use `page`, `pageSize`, and `sortBy` for pagination and ordering.

***

## Retrieve one customer

```ts theme={null}
const customer = await tagada.customers.retrieve('cus_...');
```

***

## Tags and funnel conditions

Funnel edges can branch on **customer tags**, **geo/device signals**, and related predicates. Typical **tag- and profile-driven** conditions include:

| Condition                  | Purpose                                       |
| -------------------------- | --------------------------------------------- |
| `customer.hasTag`          | Exact tag match (e.g. `vip`)                  |
| `customer.hasTagPrefix`    | Tags starting with a prefix (e.g. plan tiers) |
| `customer.hasAnyTag`       | Comma-separated list — match if any present   |
| `customer.hasAllTags`      | Comma-separated list — match if all present   |
| `customer.fromCountry`     | Country code                                  |
| `customer.fromContinent`   | Continent code                                |
| `customer.fromEU`          | EU residency heuristic                        |
| `customer.withLocale`      | Browser/locale string                         |
| `customer.withBrowser`     | Browser family                                |
| `customer.onMobile`        | Mobile device                                 |
| `customer.fromUtmSource`   | UTM / source attribution                      |
| `customer.isBot`           | Automated traffic                             |
| `customer.isChromeFamily`  | Chromium-based browser                        |
| `customer.isStandalonePWA` | Installed PWA                                 |
| `customer.isAppleSilicon`  | Apple Silicon device                          |

<Info>
  Express conditions in funnel edge `conditions.when` objects the same way as in the [Upsell & downsell funnel](/developer-tools/node-sdk/upsell-downsell-funnel) tutorial (e.g. `{ when: { 'customer.hasTag': { tag: 'vip' } } }`).
</Info>

***

## Auto-enriched tags

During funnel/checkout flows, TagadaPay can merge **device and geo tags** (and UTM-style tags from the device) onto the customer, for example:

| Tag pattern            | Example               |
| ---------------------- | --------------------- |
| `geo_country:<code>`   | `geo_country:US`      |
| `geo_continent:<code>` | `geo_continent:NA`    |
| `geo_is_eu:<bool>`     | `geo_is_eu:true`      |
| `device_type:<type>`   | `device_type:mobile`  |
| `browser:<name>`       | `browser:chrome`      |
| `utm_source:<value>`   | `utm_source:facebook` |

<Tip>
  Exact sets depend on available device data and enrichment settings. Custom query parameters can also become tags when wildcard mapping is enabled on your project.
</Tip>

***

## SDK methods reference

| Method                                  | Description                                            |
| --------------------------------------- | ------------------------------------------------------ |
| `tagada.customers.create(params)`       | Create a customer (`storeId`, `email`, optional names) |
| `tagada.customers.list(params?)`        | POST `/customers/list` with filters and pagination     |
| `tagada.customers.retrieve(customerId)` | GET a single customer                                  |

***

## Next steps

<CardGroup cols={2}>
  <Card title="Checkout sessions" icon="link" href="/developer-tools/node-sdk/checkout-sessions">
    Pre-loaded carts and `customerTags` on session links
  </Card>

  <Card title="Upsell & downsell funnel" icon="arrow-up-right-dots" href="/developer-tools/node-sdk/upsell-downsell-funnel">
    Example conditions using tags and order context
  </Card>

  <Card title="Block rules" icon="shield-halved" href="/developer-tools/node-sdk/block-rules">
    Block risky traffic and instruments at the account level
  </Card>

  <Card title="Merchant quick start" icon="rocket" href="/developer-tools/node-sdk/merchant-quickstart">
    Full SDK walkthrough from processor to checkout
  </Card>
</CardGroup>