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

# Customers

> Customer/contact records with lifecycle status, synced from your shop system.

## What it is

Customer and contact records with a lifecycle status. One row per customer, synced from your shop system (Shopify in the standard setup — `external_id` is the Shopify Customer gid). Carries contact data (email, phone, name parts, billing name/phone) plus activity timestamps (`first_seen_at`, `last_activity_at`).

[Orders](/for-agents/data-model/orders) reference customers via `customer_external_id`; the retention view [Customer Reorder Due](/for-agents/data-model/customer-reorder-due) is computed from the two together.

## How it gets data

Ingest-enabled — external systems push rows through the [Ingest API](/for-agents/ingest):

```http theme={null}
POST /api/ingest/customers
Authorization: Bearer pk_...
Content-Type: application/json
```

* One JSON record per request; unknown fields are dropped.
* **Idempotent upsert** on `(tenant_id, external_id)`.
* If `name` is missing, it is derived automatically from `first_name` / `last_name` (falling back to the billing name parts).
* `tenant_id` / `workspace_id` come from the API key context, never from the body.
* A ready-made **Make.com flow template** is downloadable in Settings → Data Sources.

Minimal example payload:

```json theme={null}
{
  "external_id": "gid://shopify/Customer/111222333",
  "email": "anna@example.com",
  "first_name": "Anna",
  "last_name": "Muster",
  "phone": "+49 170 1234567",
  "status": "active",
  "shop_source": "my-shop"
}
```

## Fields

| Field                | Label         | Type     | Writable | Description                                                                                                                  |
| -------------------- | ------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `external_id`        | External ID   | text     | ingest   | Source customer id (Shopify Customer gid) — the upsert key. Required                                                         |
| `name`               | Name          | text     | ingest   | Display name. Derived automatically from the name parts when not sent                                                        |
| `email`              | Email         | email    | ingest   | Customer email — also the identity the reorder analytics group purchases by                                                  |
| `phone`              | Phone         | text     | ingest   | Customer phone number                                                                                                        |
| `status`             | Status        | status   | ingest   | Lifecycle status of the customer (e.g. active) as delivered by the source                                                    |
| `last_activity_at`   | Last Activity | datetime | ingest   | Most recent recorded customer activity — freshness signal for retention work                                                 |
| `first_seen_at`      | First Seen    | datetime | ingest   | When the customer first appeared (first order or first sync)                                                                 |
| `first_name`         | First Name    | text     | ingest   | Customer first name                                                                                                          |
| `last_name`          | Last Name     | text     | ingest   | Customer last name                                                                                                           |
| `billing_first_name` | Billing First | text     | ingest   | First name from the billing address — name fallback when the profile has none                                                |
| `billing_last_name`  | Billing Last  | text     | ingest   | Last name from the billing address                                                                                           |
| `billing_phone`      | Billing Phone | text     | ingest   | Phone from the billing address — contact fallback                                                                            |
| `shop_source`        | Shop Source   | text     | ingest   | Which Shopify store / shop this customer originated from — per-store drill-down when several shops feed one workspace        |
| `legacy_resource_id` | Legacy ID     | text     | ingest   | Shopify numeric customer id (`legacyResourceId`); `external_id` holds the gid, which is the upsert key                       |
| `segments`           | —             | json     | API only | Customer segments/lists from the source system. Not shown in the app's table, but accepted on ingest and returned by queries |
| `metadata`           | —             | json     | API only | Raw source fields that don't map to a column — kept so nothing from the source payload is lost                               |

"ingest" = populated through the ingest endpoint; read-only in the app and over MCP row writes. "API only" = real database column that is not registered as a visible app column.

<Note>
  Like every workspace table, customers also carry the system columns `id`, `tenant_id`, `workspace_id`, `created_at`, and `updated_at` — set automatically, never sent by integrations.
</Note>

## Query it

```json theme={null}
{
  "method": "tools/call",
  "params": {
    "name": "data_query",
    "arguments": {
      "view_slug": "customers",
      "search": "anna",
      "select_fields": ["name", "email", "status", "last_activity_at"],
      "limit": 25
    }
  }
}
```