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

# Retrieve a customer by email

> Retrieves a single customer by their email address.

The response includes the customer's current VIP tier and loyalty membership status. To fetch many customers at once, use [List customers](https://docs.yuko.so/developer/api/list-customers.md).

> [!NOTE]
>
> Requires the `read:customers` scope. The `points`, `referral_code`/`referral_url` and `tier` fields are only included when the key also has the `points`, `referrals` and `tiers` scopes. See [Scopes](https://docs.yuko.so/developer/api/scopes.md).

## Path parameters

**email** `string` *required*

The customer's email address. Yuko lowercases it before matching. URL-encode it (for example `@` becomes `%40`).

## Response

**data** `object`

The customer. Has the properties of the [Customer object](https://docs.yuko.so/customer-identity-object.md), plus `tier` and `membership`. Some fields depend on the key's other scopes, as noted below.

**customer properties**

**id** `string\<uuid\>`

Yuko's unique identifier for the customer.

**first\_name** `string | null`

The customer's first name.

**last\_name** `string | null`

The customer's last name.

**email** `string | null`

The customer's email address.

**phone** `string | null`

The customer's phone number.

**platform** `string`

The platform the customer was synced from, for example `shopify`.

**platform\_customer\_id** `string | null`

The customer's ID in your store, for example the Shopify customer ID.

**state** `enum\<string\>`

`member` for customers in the loyalty program, or `disabled` for customers you've banned from it. Customers excluded only by a customer tag still show `member`.

**date\_of\_birth** `string\<date\> | null`

The customer's birthday in `YYYY-MM-DD` format, if collected.

**referral\_code** `string | null`

Only returned when the key also has a `referrals` scope. The customer's referral code, or `null` if they don't have one yet.

**referral\_url** `string | null`

Only returned when the key also has a `referrals` scope. The customer's referral link: the referral landing page URL plus `?ref=<referral_code>`. `null` if there's no referral code or no landing page URL is set.

**points** `object`

Only returned when the key also has a `points` scope. The customer's points summary.

**points properties**

**balance** `integer`

Current redeemable points balance. Always `0` for customers who are banned or excluded from the loyalty program by a customer tag.

**earned** `integer`

Total points ever earned.

**redeemed** `integer`

Total points redeemed.

**tier** `object | null`

Only returned when the key also has a `tiers` scope. The customer's current VIP tier, with the same fields as a tier in [List VIP tiers](https://docs.yuko.so/developer/api/list-vip-tiers.md). `null` if the customer hasn't reached a tier or VIP tiers are turned off.

**tier properties**

**id** `string\<uuid\>`

The tier's unique identifier.

**name** `string`

The tier's name.

**threshold\_value** `integer`

The qualifying value needed to reach the tier.

**multiplier** `number`

The tier's points multiplier.

**multiplier\_label** `string`

The label shown for the multiplier, for example `Earn [multiplier] [points_label]`.

**icon** `object | null`

The tier's icon, or `null` if none is set.

**benefits** `object[]`

The tier's benefits, each with `name`, `benefit_type` and `benefit_value`.

**created\_at** `string\<date-time\>`

When the tier was created.

**membership** `object`

Loyalty membership summary.

**membership properties**

**status** `string`

Always `active`.

**member\_since** `string\<date-time\>`

When the customer was created in Yuko (same as `created_at`).

**created\_at** `string\<date-time\>`

When the customer was created in Yuko (ISO 8601).

**updated\_at** `string\<date-time\>`

When the customer was last updated in Yuko (ISO 8601).

## Errors

| Status | Code | When |
| :- | :- | :- |
| `401` | `missing_token`, `invalid_token` | The API key is missing, wrong or revoked. |
| `403` | `insufficient_scope` | The key doesn't have `read:customers`. |
| `404` | `not_found` | No customer matches `email`. Message: "Customer not found". |
| `429` | | You exceeded the [rate limit](https://docs.yuko.so/developer/api/rate-limits.md). |

```bash cURL theme={null}
curl --request GET \
  --url "https://api.yukoapp.com/api/v1/public/customers/by-email/jane.smith%40example.com" \
  --header "Authorization: Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

```javascript JavaScript theme={null}
const email = "jane.smith@example.com";

const response = await fetch(
  `https://api.yukoapp.com/api/v1/public/customers/by-email/${encodeURIComponent(email)}`,
  {
    method: "GET",
    headers: {
      Authorization: "Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    },
  }
);

const data = await response.json();
```

```php PHP theme={null}
$email = "jane.smith@example.com";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.yukoapp.com/api/v1/public/customers/by-email/" . rawurlencode($email));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
```

```json 200 theme={null}
{
  "data": {
    "id": "63a2c89a-9936-4bc0-9d5f-93db46110b76",
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane.smith@example.com",
    "phone": "+14155552671",
    "platform": "shopify",
    "platform_customer_id": "9049402769586",
    "state": "member",
    "date_of_birth": "1990-04-12",
    "referral_code": "JANE10",
    "referral_url": "https://example.com/pages/refer?ref=JANE10",
    "points": {
      "balance": 350,
      "earned": 500,
      "redeemed": 150
    },
    "created_at": "2024-06-01T10:00:00+00:00",
    "updated_at": "2026-02-15T08:30:00+00:00",
    "tier": {
      "id": "7fb39c85-3a3f-4247-8333-2e05a9c8ae28",
      "name": "Silver",
      "threshold_value": 500,
      "multiplier": 1.5,
      "multiplier_label": "Earn [multiplier] [points_label]",
      "icon": null,
      "benefits": [],
      "created_at": "2025-09-12T15:44:44+00:00"
    },
    "membership": {
      "status": "active",
      "member_since": "2024-06-01T10:00:00+00:00"
    }
  }
}
```

```json 404 theme={null}
{
  "error": {
    "code": "not_found",
    "message": "Customer not found"
  }
}
```

```json 401 theme={null}
{
  "error": {
    "code": "invalid_token",
    "message": "Invalid or revoked API token"
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.