List loyalty customers

GET /customers


Scope	`customers:read`
Customer session token	Not accepted: call from your server with an API key
Rate limit class	`read` (limits)
Idempotency key	Not used
MCP tool	`charm_list_customers`

Cursor-paginated list of enrolled customers. Filter by email for an exact, case-insensitive match.

Parameters

Name	In	Type	Description
`limit` (optional)	query	integer	Page size, 1–250. Defaults to 50.
`cursor` (optional)	query	string	Opaque cursor from a previous response’s `next_cursor`.
`email` (optional)	query	string	Exact e-mail match.

Response `200`

Returns CustomerList.

Field	Type	Description
`data`	array of Customer
`next_cursor`	string or null	Pass as `cursor` to fetch the next page; null on the last page. (nullable)
`has_more`	boolean	True when another page exists.

{
  "data": [
    {
      "id": "gid://shopify/Customer/7712345",
      "legacy_id": 7712345,
      "email": "shopper@example.com",
      "first_name": "Jane",
      "last_name": "Doe",
      "points_balance": 120,
      "points_earned": 120,
      "points_redeemed": 120,
      "pending_points": 120,
      "tier": null,
      "next_tier": null,
      "rewards": [
        null
      ],
      "history": [
        null
      ],
      "program": {
        "enabled": null,
        "program_name": null,
        "points_name": null,
        "points_expiry": null,
        "reward_expiry": null,
        "eligibility": null,
        "referral": null,
        "memberships_enabled": null,
        "tiers_enabled": null,
        "earning_rules": null,
        "redemption_rules": null,
        "revision": null,
        "updated_at": null
      },
      "referral": null,
      "referral_code": "JANE10",
      "excluded_from_program": false,
      "enrolled_at": "2026-10-01T09:30:00.000Z",
      "enrolled_via": "Embedded Widget",
      "birthday": null,
      "orders_count": 1,
      "lifetime_spend": 1,
      "last_activity_at": "2026-10-01T09:30:00.000Z",
      "updated_at": "2026-10-01T09:30:00.000Z"
    }
  ],
  "next_cursor": null,
  "has_more": true
}

Example

curl -X GET "https://charm.appfleece.app/api/v1/customers" \
  -H "Authorization: Bearer chrm_live_..."

Errors

unauthorized · invalid_token · insufficient_scope · access_required · validation_error · rate_limited

Every error body carries code, message, request_id and a doc_url pointing at the matching entry in the error catalog.