List customers

curl --request GET \
  --url "https://api.yukoapp.com/api/v1/public/customers?per_page=20&page=1" \
  --header "Authorization: Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

const params = new URLSearchParams({ per_page: 20, page: 1 });

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

const data = await response.json();

$query = http_build_query(["per_page" => 20, "page" => 1]);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.yukoapp.com/api/v1/public/customers?{$query}");
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);

{
  "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": "7823491023",
      "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"
    }
  ],
  "meta": {
    "pagination": {
      "current_page": 1,
      "per_page": 20,
      "total": 1,
      "last_page": 1,
      "has_more": false
    }
  }
}

{
  "error": {
    "code": "invalid_token",
    "message": "Invalid or revoked API token"
  }
}

GET

public

customers

curl --request GET \
  --url "https://api.yukoapp.com/api/v1/public/customers?per_page=20&page=1" \
  --header "Authorization: Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

const params = new URLSearchParams({ per_page: 20, page: 1 });

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

const data = await response.json();

$query = http_build_query(["per_page" => 20, "page" => 1]);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.yukoapp.com/api/v1/public/customers?{$query}");
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);

{
  "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": "7823491023",
      "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"
    }
  ],
  "meta": {
    "pagination": {
      "current_page": 1,
      "per_page": 20,
      "total": 1,
      "last_page": 1,
      "has_more": false
    }
  }
}

{
  "error": {
    "code": "invalid_token",
    "message": "Invalid or revoked API token"
  }
}

Results are sorted by created_at, newest first. To fetch a single customer, use Retrieve a customer.

Requires the read:customers scope. See Scopes.

Query parameters

string

Return only the customer whose email address exactly matches this value.

enum<string>

Return only customers synced from this platform. One of shopify, woocommerce.

integer

default:20

The number of results per page. Values above 100 are treated as 100.

integer

default:1

The page number to retrieve. See Classic pagination.

Response

object[]

The customers on this page. Each customer has the properties of the Customer object.

Show customer properties

string<uuid>

Yuko’s unique identifier for the customer.

string | null

The customer’s first name.

string | null

The customer’s last name.

string | null

The customer’s email address.

string | null

The customer’s phone number.

string

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

string | null

The customer’s ID in your store. Pass this value as customer_id to other endpoints.

enum<string>

member for active loyalty members, or disabled if the customer is banned from the loyalty program.

string<date> | null

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

string | null

The customer’s referral code. null if the customer has no referral code yet.

string | null

The customer’s referral link, built from the referral landing page URL plus ?ref=<referral_code>. null if there’s no referral code or no landing page URL is set.

object

The customer’s points totals.

Show points properties

integer

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

integer

Total points ever earned.

integer

Total points redeemed.

string<date-time>

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

string<date-time>

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

object

Show meta properties

object

Pagination details. See Classic pagination.

Show pagination properties

integer

The page returned.

integer

The number of records per page.

integer

The total number of records.

integer

The number of the last page.

boolean

true if there are more pages after this one.

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`.
`429`		The key exceeded the rate limit.

curl --request GET \
  --url "https://api.yukoapp.com/api/v1/public/customers?per_page=20&page=1" \
  --header "Authorization: Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

const params = new URLSearchParams({ per_page: 20, page: 1 });

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

const data = await response.json();

$query = http_build_query(["per_page" => 20, "page" => 1]);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.yukoapp.com/api/v1/public/customers?{$query}");
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);

{
  "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": "7823491023",
      "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"
    }
  ],
  "meta": {
    "pagination": {
      "current_page": 1,
      "per_page": 20,
      "total": 1,
      "last_page": 1,
      "has_more": false
    }
  }
}

{
  "error": {
    "code": "invalid_token",
    "message": "Invalid or revoked API token"
  }
}

Rest API

API References

Object Reference

Query parameters

Response

Errors

​Query parameters

​Response

​Errors

Query parameters

Response

Errors