Μέλη

Πελάτης εγγεγραμμένος στο πρόγραμμα επιβράβευσης της επιχείρησης, με μία κάρτα Wallet.

Το αντικείμενο member

iduuid: Το δικό μας id του πελάτη.
card_numberstring: Ο αριθμός στην κάρτα. Δικός μας (13 ψηφία) ή αυτός που ορίσατε.
serialuuid: Το serial της κάρτας Wallet.
first_name, last_name, phone, email, birthday, languagestring: Προφίλ. Το phone είναι σε διεθνή μορφή (+37366791102), το birthday σε μορφή YYYY-MM-DD.
marketing_consentboolean: Ο πελάτης συμφώνησε να λαμβάνει διαφημιστικά μηνύματα.
programobject: Τα id, name, mechanic και η μορφή barcode του προγράμματος του μέλους.
stampsobject ή null: current, required, rewards_available. Null για προγράμματα χωρίς σφραγίδες.
cashbackobject ή null: balance (στη μικρότερη υποδιαίρεση), held σε ενεργές δεσμεύσεις, available προς χρήση, currency, earn_rate (ποσοστό), level, level_basis, levels, next_level, redeem_max_percent, min_amount, expires_at. Null για προγράμματα χωρίς cashback. Δείτε επίπεδα cashback.
discountobject ή null: percent, tier, next_at_visits για προγράμματα έκπτωσης βάσει επισκέψεων.
visits, total_spentinteger: Συνολικές επισκέψεις και συνολικό ποσό δαπανών.
walletobject ή null: apple_url, google_url, card_url: υπογεγραμμένοι σύνδεσμοι για προσθήκη της κάρτας. Επιστρέφονται κατά τη δημιουργία και με ?expand=wallet.

Παράμετρος	Τύπος	Περιγραφή
id	uuid	Το δικό μας id του πελάτη.
card_number	string	Ο αριθμός στην κάρτα. Δικός μας (13 ψηφία) ή αυτός που ορίσατε.
serial	uuid	Το serial της κάρτας Wallet.
first_name, last_name, phone, email, birthday, language	string	Προφίλ. Το `phone` είναι σε διεθνή μορφή (`+37366791102`), το `birthday` σε μορφή `YYYY-MM-DD`.
marketing_consent	boolean	Ο πελάτης συμφώνησε να λαμβάνει διαφημιστικά μηνύματα.
program	object	Τα `id`, `name`, `mechanic` και η μορφή `barcode` του προγράμματος του μέλους.
stamps	object ή null	`current`, `required`, `rewards_available`. Null για προγράμματα χωρίς σφραγίδες.
cashback	object ή null	`balance` (στη μικρότερη υποδιαίρεση), `held` σε ενεργές δεσμεύσεις, `available` προς χρήση, `currency`, `earn_rate` (ποσοστό), `level`, `level_basis`, `levels`, `next_level`, `redeem_max_percent`, `min_amount`, `expires_at`. Null για προγράμματα χωρίς cashback. Δείτε επίπεδα cashback.
discount	object ή null	`percent`, `tier`, `next_at_visits` για προγράμματα έκπτωσης βάσει επισκέψεων.
visits, total_spent	integer	Συνολικές επισκέψεις και συνολικό ποσό δαπανών.
wallet	object ή null	`apple_url`, `google_url`, `card_url`: υπογεγραμμένοι σύνδεσμοι για προσθήκη της κάρτας. Επιστρέφονται κατά τη δημιουργία και με `?expand=wallet`.

JSON

{
  "object": "member",
  "id": "6dacfe0a-2500-44c6-a37c-05c660b093b4",
  "card_number": "2000111703779",
  "serial": "b90273b1-10c9-46eb-ba74-8fef48266b5d",
  "first_name": "Ion",
  "last_name": "Popescu",
  "phone": "+37366791102",
  "email": null,
  "birthday": null,
  "language": "ro",
  "marketing_consent": false,
  "program": {
    "id": "06af6eba-eaf5-4662-8a5e-2b6b52c65314",
    "name": "Sandbox Cashback",
    "mechanic": "cashback",
    "barcode": "card_code128"
  },
  "stamps": null,
  "cashback": {
    "balance": 1250,
    "currency": "MDL",
    "earn_rate": 5,
    "level": null,
    "redeem_max_percent": 30,
    "min_amount": 10000,
    "expires_at": "2027-01-04T18:17:17.721+00:00"
  },
  "discount": null,
  "visits": 1,
  "total_spent": 25000,
  "wallet": {
    "apple_url": "https://loyaltyfy.io/api/wallet/issue/3832466f-...?platform=apple&t=...",
    "google_url": "https://loyaltyfy.io/api/wallet/issue/3832466f-...?platform=google&t=...",
    "card_url": "https://loyaltyfy.io/wallet/3832466f-...?t=..."
  },
  "created_at": "2026-10-06T18:17:15.594+00:00"
}

POST/v1/members

Δικαίωμα: members:write ή devices:write

Εγγράφει έναν πελάτη και εκδίδει την κάρτα Wallet. Αν υπάρχει ήδη μέλος με αυτό το τηλέφωνο, επιστρέφει αυτό το μέλος με 200 αντί για 201. Στείλτε Idempotency-Key.

phonestring, υποχρεωτικό: Διεθνής μορφή. Γίνονται δεκτές και οι τοπικές μορφές της χώρας της επιχείρησης.
first_namestring, υποχρεωτικό: Έως 80 χαρακτήρες.
consenttrue, υποχρεωτικό: Επιβεβαιώνει ότι ο πελάτης συμφώνησε στην επεξεργασία των δεδομένων του. Αιτήματα χωρίς αυτό απορρίπτονται.
last_name, email, birthday, languagestring: Προαιρετικά πεδία προφίλ. Το language (en, ro, ru, es...) χρησιμοποιείται για την κάρτα και τα μηνύματα.
card_numberstring: Από 4 έως 32 γράμματα, ψηφία ή παύλες. Χρησιμοποιήστε τον αριθμό κάρτας του ίδιου του ταμείου. Μοναδικός ανά επιχείρηση.
programstring: Το slug του προγράμματος από το GET /v1/account. Προεπιλογή: το κύριο πρόγραμμα της επιχείρησης.
marketing_consentboolean: Ο πελάτης συμφώνησε να λαμβάνει διαφημιστικά μηνύματα. Προεπιλογή false.

Παράμετρος	Τύπος	Περιγραφή
phone	string, υποχρεωτικό	Διεθνής μορφή. Γίνονται δεκτές και οι τοπικές μορφές της χώρας της επιχείρησης.
first_name	string, υποχρεωτικό	Έως 80 χαρακτήρες.
consent	true, υποχρεωτικό	Επιβεβαιώνει ότι ο πελάτης συμφώνησε στην επεξεργασία των δεδομένων του. Αιτήματα χωρίς αυτό απορρίπτονται.
last_name, email, birthday, language	string	Προαιρετικά πεδία προφίλ. Το `language` (`en`, `ro`, `ru`, `es`...) χρησιμοποιείται για την κάρτα και τα μηνύματα.
card_number	string	Από 4 έως 32 γράμματα, ψηφία ή παύλες. Χρησιμοποιήστε τον αριθμό κάρτας του ίδιου του ταμείου. Μοναδικός ανά επιχείρηση.
program	string	Το `slug` του προγράμματος από το `GET /v1/account`. Προεπιλογή: το κύριο πρόγραμμα της επιχείρησης.
marketing_consent	boolean	Ο πελάτης συμφώνησε να λαμβάνει διαφημιστικά μηνύματα. Προεπιλογή false.

curl

curl https://loyaltyfy.io/api/v1/members \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7d1b2c4e-enrol-000123" \
  -d '{
    "phone": "+37366791102",
    "first_name": "Ion",
    "last_name": "Popescu",
    "card_number": "2000111703779",
    "language": "ro",
    "consent": true
  }'

Ορισμένα προγράμματα δίνουν σφραγίδα καλωσορίσματος κατά την εγγραφή, οπότε ένα νέο μέλος μπορεί να ξεκινά με stamps.current: 1.

GET/v1/members/{member}

Δικαίωμα: members:read

Το {member} είναι αριθμός κάρτας, τιμή σαρωμένου barcode, serial της κάρτας Wallet, id μέλους ή τηλέφωνο (κωδικοποιημένο για URL). Προσθέστε ?expand=wallet για νέους συνδέσμους προσθήκης στο Wallet.

curl

# by the number on the card (or the barcode the scanner read)
curl https://loyaltyfy.io/api/v1/members/2000111703779 \
  -H "Authorization: Bearer sk_test_..."

# by phone, with fresh add-to-wallet links
curl "https://loyaltyfy.io/api/v1/members/%2B37366791102?expand=wallet" \
  -H "Authorization: Bearer sk_test_..."

PATCH/v1/members/{member}

Δικαίωμα: members:write

Ενημερώνει πεδία προφίλ ή συνδέει αριθμό κάρτας από το ταμείο. Στείλτε μόνο τα πεδία που αλλάζετε: phone, first_name, last_name, email, birthday, language, card_number, marketing_consent.

curl

curl -X PATCH https://loyaltyfy.io/api/v1/members/%2B37366791102 \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "card_number": "2000111703779", "birthday": "1990-04-12" }'

GET/v1/members

Δικαίωμα: members:read

Επιστρέφει τα μέλη, με τα νεότερα πρώτα. Με σελιδοποίηση. Με ?phone= ή ?card_number= επιστρέφει αντί γι' αυτό λίστα με κανένα ή ένα μέλος.

curl

curl "https://loyaltyfy.io/api/v1/members?limit=50" \
  -H "Authorization: Bearer sk_test_..."

GET/v1/members/{member}/history

Δικαίωμα: members:read

Κάθε αλλαγή στην κάρτα, με τις νεότερες πρώτες, ανεξάρτητα από την αιτία: το API, η εφαρμογή ταμείου της επιχείρησης, ένα POS, μια σύνδεση κρατήσεων. Το type είναι accrual, cashback, cashback_earn, gift, reward_redeemed, reversal και μπορεί να αποκτήσει νέες τιμές. Το source είναι api, pos, cashier ή system. Με σελιδοποίηση.

Απάντηση · 200

{
  "object": "list",
  "url": "/v1/members/2000111703779/history",
  "has_more": false,
  "data": [
    {
      "object": "history_entry",
      "id": "937310bd-cb77-49a0-a4ff-855399f5cde3",
      "type": "cashback_earn",
      "stamps_delta": 0,
      "cashback_delta": 1250,
      "amount": 25000,
      "reward_unlocked": false,
      "source": "system",
      "external_id": null,
      "created_at": "2026-10-06T18:17:17.790+00:00"
    }
  ]
}

POST/v1/members/{member}/rewards/redeem

Δικαίωμα: transactions:write ή devices:write

Δίνει στο μέλος μία κερδισμένη επιβράβευση σφραγίδων και μειώνει το stamps.rewards_available. Απορρίπτεται με no_reward_available όταν δεν υπάρχει. Στείλτε Idempotency-Key.

curl

curl -X POST https://loyaltyfy.io/api/v1/members/4285324286429/rewards/redeem \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: reward-4285324286429-0001"

POST/v1/members/{member}/adjustments

Δικαίωμα: members:adjust

Προσθέτει (θετικό amount) ή αφαιρεί (αρνητικό) cashback με reason από 3 έως 300 χαρακτήρες. Λειτουργεί μόνο όταν η επιχείρηση επιτρέπει διορθώσεις, έως το όριό της ανά διόρθωση. Η επανάληψη ενός external_id επιστρέφει την αποθηκευμένη διόρθωση. Στέλνει balance.adjusted.

curl

curl https://loyaltyfy.io/api/v1/members/2000111703779/adjustments \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "external_id": "ADJ-2026-0009", "amount": 2000, "reason": "Goodwill after a complaint" }'

# a negative amount takes cashback away