Members & POPIA

The Loyalty Engine uses your existing customer identifiers — no account migration required. Pass your customer ID as memberRef in every evaluate() call. It is stored as externalRef on the member record and returned in API responses (any stable identifier works — customer ID, loyalty card number, phone hash, etc).

Auto-creation

You do not need to pre-create members. When a transaction is evaluated for an unknown memberRef, a member is automatically created and linked to the tenant. The member's Loyalty Engine UUID is returned as memberId in the transaction response.

// Member is auto-created on first evaluate() call
const result = await client.POST('/tenants/{tenantId}/transactions/evaluate', {
  body: {
    transactionRef: 'txn_001',
    memberRef:      'customer_id_from_your_system',  // ← your identifier
    amount:         15000,
  },
});

// result.data.memberId is the Loyalty Engine member UUID
console.log(result.data?.memberId);      // 9f4c2e8a-...
console.log(result.data?.memberCreated); // true (first-time enrolment)

POPIA compliance

South Africa's Protection of Personal Information Act (POPIA) requires explicit consent before processing personal data. The Loyalty Engine provides a consent API that records when, how, and for what purpose a member consented.

You must record consent before or at the time a member joins your loyalty programme. Transactions can still be evaluated without consent — but you may not use personal data for marketing or profiling without it.

// Record consent — requires the member's Loyalty Engine UUID
// (returned from evaluate() as memberId, or looked up via GET /members?ref=)
await client.POST('/tenants/{tenantId}/members/{memberId}/consent', {
  body: {
    purpose:        'LOYALTY_PROGRAMME',  // note: UK spelling
    consentVersion: 'v1.0',              // version of consent text shown
    channel:        'WEB',
  },
});

// Withdraw consent (right to object)
await client.DELETE(
  '/tenants/{tenantId}/members/{memberId}/consent/LOYALTY_PROGRAMME',
);

Right to erasure

Under POPIA, members have the right to request deletion of their personal data. The Loyalty Engine anonymises the member record (nulls all PII fields) while retaining points and reward transaction history for financial audit purposes.

// Right to erasure — removes all personal data
await client.DELETE('/tenants/{tenantId}/members/{memberId}', {
  params: { path: { tenantId: 'tenant_abc', memberId: 'mem_01HX...' } },
});
// Member record is anonymised. Points & reward history is retained for financial audit.

Phone & email display

The Loyalty Engine API returns masked values by default. Pass ?unmask=true only from server-side code in a context where the customer has explicitly requested to see their data.