Customer lookup Available

At checkout, look up a customer's live loyalty status so the till can show their balance, tier, the rewards they can redeem right now, and their stamp progress. This is a pure read — it never changes anything.

GET /api/partner/v1/customers/lookup

Authenticated with X-Api-Key only — a GET carries no body, so it needs no X-Signature. The tenant is derived from your key.

Fail open at the till

Treat this call as best-effort: if it is slow or unavailable, complete the sale without the loyalty preview rather than blocking the customer. Only redemption and refund checks fail closed.

Identifying the customer

Pass exactly one of these query parameters. Sending neither, or both, is a 400 INVALID_REQUEST.

Parameter	Meaning
`phone`	E.164 phone typed at the till, e.g. `+966512345678`.
`customerId`	The Quroosh customer UUID, scanned from the customer's identity or wallet QR.

An unknown customer is not an error — it returns200 with isEnrolled: false and every other field null.

Response

Field	Type	Notes
`isEnrolled`	boolean	`false` means no profile for this customer — all other fields are null.
`customerId`	string (UUID) / null	The Quroosh customer id.
`externalCustomerId`	string / null	Your id for this customer. Null for a Quroosh-native customer never synced from your system.
`phone`	string / null	E.164.
`name`	string / null	Display name.
`profileStatus`	enum / null	`Active` or `Imported` (silently imported, never logged in).
`currentPointsBalance`	integer / null	Redeemable points balance.
`tierName`	string / null	Loyalty tier, if the store runs tiers.
`redeemableRewards`	array / null	Rewards the customer can redeem right now — sufficient balance, active, in-window.
`stampProgress`	array / null	Per-card stamp progress and cooldown eligibility.

redeemableRewards[]:

Field	Type	Notes
`rewardId`	string (UUID)	Pass this back when validating a redemption.
`nameAr` / `nameEn`	string	Display per your POS locale.
`source`	enum	How it is paid for: `Points`, `Stamps`, or `Reward`.
`rewardType`	enum	`Product`, `Service`, or `Coupon`.
`pointsCost`	integer / null	Set only for points rewards.

stampProgress[]:

Field	Type	Notes
`stampCardId`	string (UUID)	The card.
`stampCardName`	string	Display name.
`collected` / `total`	integer	Progress toward a full card.
`eligibleForStamp`	boolean	`false` while a per-visit cooldown is running — grey the card out.
`cooldownUntil`	string (ISO) / null	When the card becomes eligible again; null when already eligible.

Scenarios

Enrolled

{
  "isEnrolled": true,
  "customerId": "0195d0d0-0000-7000-8000-000000000abc",
  "externalCustomerId": "cust_012345",
  "phone": "+966512345678",
  "name": "Sara Al-Otaibi",
  "profileStatus": "Active",
  "currentPointsBalance": 420,
  "tierName": "Gold",
  "redeemableRewards": [
    {
      "rewardId": "0195d0e0-0000-7000-8000-000000000001",
      "nameAr": "قهوة مجانية",
      "nameEn": "Free coffee",
      "source": "Points",
      "rewardType": "Product",
      "pointsCost": 200
    }
  ],
  "stampProgress": [
    {
      "stampCardId": "0195d0b0-0000-7000-8000-0000000000aa",
      "stampCardName": "Coffee card",
      "collected": 6,
      "total": 10,
      "eligibleForStamp": true,
      "cooldownUntil": null
    }
  ]
}

Unknown customer

A normal 200, not an error.

{
  "isEnrolled": false,
  "customerId": null,
  "externalCustomerId": null,
  "phone": null,
  "name": null,
  "profileStatus": null,
  "currentPointsBalance": null,
  "tierName": null,
  "redeemableRewards": null,
  "stampProgress": null
}

Imported (never logged in)

A profile Quroosh created silently from your CustomerSynceddata. It earns from day one; profileStatus isImported.

{
  "isEnrolled": true,
  "externalCustomerId": "cust_012346",
  "phone": "+966512345679",
  "name": "Faisal Al-Harbi",
  "profileStatus": "Imported",
  "currentPointsBalance": 60,
  "tierName": null,
  "redeemableRewards": [],
  "stampProgress": []
}

Quroosh-native (scanned QR)

A Quroosh customer who has never been synced from your system —externalCustomerId is null. Look them up bycustomerId from their identity QR.

{
  "isEnrolled": true,
  "customerId": "0195d0d0-0000-7000-8000-000000000abe",
  "externalCustomerId": null,
  "phone": "+966512345680",
  "name": "Noura Al-Qahtani",
  "profileStatus": "Active",
  "currentPointsBalance": 1500,
  "tierName": "Platinum",
  "redeemableRewards": [],
  "stampProgress": []
}

Stamp card mid-cooldown

{
  "stampProgress": [
    {
      "stampCardId": "0195d0b0-0000-7000-8000-0000000000ab",
      "stampCardName": "Lunch card",
      "collected": 3,
      "total": 8,
      "eligibleForStamp": false,
      "cooldownUntil": "2026-07-17T00:00:00Z"
    }
  ]
}

Example

using System.Net.Http.Json;

using var http = new HttpClient { BaseAddress = new Uri("https://api.quroosh.io/") };
http.DefaultRequestHeaders.Add("X-Api-Key", apiKey);

// Identify by E.164 phone OR Quroosh customerId — exactly one.
var customer = await http.GetFromJsonAsync<CustomerLookupResponse>(
    "api/partner/v1/customers/lookup?phone=+966512345678");

if (customer!.IsEnrolled)
    Console.WriteLine($"{customer.Name}: {customer.CurrentPointsBalance} points");

The full schema and a try-it playground are on theAPI Reference.