Customers

Before earning or redeeming, you need a customer_code. Use these endpoints to look up an existing customer or enroll a new one at checkout.

Look Up a Customer

GET /webhook/customer?code={customer_code}
GET /webhook/customer?qr={qr_payload}
X-Api-Key: {your_secret_key}

Returns balance and masked contact info. Two lookup modes:

Parameter	When to use
`?code=482193`	You already know the `customer_code` (e.g. from a previous enrollment response)
`?qr=<payload>`	You scanned the customer's QR code — pass the raw QR content directly

The ?qr= mode verifies the HMAC signature and expiry embedded in the QR payload before returning the customer. Expired or tampered QR codes are rejected.

Where does the QR payload come from? The QR code is displayed in the customer's Loyalite profile page (customer dashboard). When the customer shows their QR code, scan it with your POS device and pass the raw string content verbatim as the ?qr= value. QR codes expire after 24 hours — the customer can refresh their QR from the dashboard at any time.

Response

{
  "data": {
    "customer_code": 482193,
    "masked_email": "a***@gmail.com",
    "stamp_count": 4,
    "point_balance": 120
  }
}

Error cases

Condition	HTTP	Error code
Neither `code` nor `qr` provided	400	`code or qr is required`
QR payload expired or tampered	422	`invalid_qr`
Customer not in your org	404	`customer_not_found`

Enroll a Customer

Use this when a customer wants to join your loyalty program at checkout — for example, when they provide their email to earn points on an online order.

This endpoint is idempotent: if the email already belongs to an existing customer in your org, it returns that customer without creating a duplicate.

POST /webhook/customer
X-Api-Key: {your_secret_key}
Content-Type: application/json

Request body

{
  "email": "[email protected]",
  "consent_terms": true,
  "consent_privacy": true,
  "consent_marketing": false
}

Field	Required	Description
`email`	✅	Customer's email address
`consent_terms`	✅	Must be `true` — terms of service consent
`consent_privacy`	✅	Must be `true` — privacy policy consent
`consent_marketing`	❌	Optional marketing communications consent

Your responsibility: You must display the Loyalite Terms of Service and Privacy Policy to the customer before calling this endpoint, and only set consent_terms: true and consent_privacy: true when the customer has actively agreed.

Response — new customer (201)

{
  "data": {
    "customer_code": 482193,
    "is_new": true,
    "masked_email": "a***@example.com",
    "stamp_count": 0,
    "point_balance": 0
  }
}

Response — existing customer (200)

{
  "data": {
    "customer_code": 482193,
    "is_new": false,
    "masked_email": "a***@example.com",
    "stamp_count": 4,
    "point_balance": 120
  }
}

Use is_new to show a welcome message for first-time members.

Error cases

Condition	HTTP	Error code
`email` missing	422	`email_required`
`consent_terms` is `false`	422	`consent_terms_required`
`consent_privacy` is `false`	422	`consent_privacy_required`

Overview Transactions