API and webhooks / Reference / Add a visit
Add a visit
POST /v1/passages adds a stamp or points to a customer's card from your POS, and tells you whether a reward is earned.
POST
/v1/passagesThe equivalent of a scan at the counter, sent by your POS: one stamp (or several), or points. The rules and limits are those of the counter, the customer's card updates in their Wallet, and the visit counts like any other (regulars, reminders, review request).
Body (JSON)
clientobjectrequired
Who gets the visit: one of
id, carte (the card code), email or telephone.montantnumberoptional
Receipt amount, in units (
12.5 for €12.50). If the business has a "€10 = 1 stamp" rule, the amount takes precedence over quantite; in points mode, it is converted with the business's points-per-euro rule.quantiteintegeroptional
Stamps and tiers modes: number of stamps, 1 by default, 50 at most.
pointsintegeroptional
Points mode, without an amount: the points to add. By default, the business's value.
referencestringoptional
The receipt number. A reference only adds a stamp once per business.
creer_si_absentbooleanoptional
true: an unknown customer, identified by email or telephone, is created (with prenom and nom if they are in client). Default false.conditions_accepteesbooleanoptional
When the business requires its terms and
creer_si_absent creates the customer (in client or at the root).Example
curl https://app.stampywallet.com/v1/passages \
-H "Authorization: Bearer sw_live_your_key" \
-H "Content-Type: application/json" \
-d '{
"client": { "telephone": "+33612345678", "prenom": "Léa" },
"montant": 12.5,
"reference": "TICKET-4512",
"creer_si_absent": true
}'const r = await fetch('https://app.stampywallet.com/v1/passages', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.STAMPY_CLE}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
client: { telephone: '+33612345678', prenom: 'Léa' },
montant: 12.5,
reference: 'TICKET-4512',
creer_si_absent: true,
}),
});
const resultat = await r.json();
if (resultat.recompense_atteinte) console.log('Reward to give!');import os, requests
r = requests.post(
"https://app.stampywallet.com/v1/passages",
headers={"Authorization": f"Bearer {os.environ['STAMPY_CLE']}"},
json={"client": {"telephone": "+33612345678", "prenom": "Léa"},
"montant": 12.5, "reference": "TICKET-4512", "creer_si_absent": True},
)
print(r.json()["recompense_atteinte"])Response
{
"passage": {
"id": "226fdea1-ba59-49fb-93e6-60a14a765134",
"client_id": "c2a91f3e-7d40-4b8a-a3c5-91e0d6f4b2c7",
"valeur": 1,
"montant": 12.5,
"reference": "TICKET-4512",
"cree_le": "2026-10-22T09:20:00.000Z"
},
"rejoue": false,
"client_cree": false,
"recompense_atteinte": true,
"recompenses_gagnees": 1,
"plafonne": false,
"client": { "id": "c2a91f3e-7d40-4b8a-a3c5-91e0d6f4b2c7", "prenom": "Léa", "etat": { "tampons": 0, "objectif": 10 } }
}| Field | Meaning |
|---|---|
passage.valeur | The stamps or points added |
passage.montant | The recorded amount, or null |
rejoue | true when the reference had already been used: the response is then 200 and returns the original visit, without adding a stamp a second time |
client_cree | true if creer_si_absent created the customer |
recompense_atteinte, recompenses_gagnees | This visit earns a reward (or several): to give when the customer takes it |
plafonne | true if the value was brought down to the counter's cap |
client | The customer object after the visit |
Refusals
| Status | code | When |
|---|---|---|
404 | client_introuvable | No customer matches, and creer_si_absent is not true |
409 | trop_tot | A visit from the same customer happened less than the business's double-visit delay ago (90 seconds by default) |
422 | montant_insuffisant | The amount does not make one stamp (or one point) |
422 | conditions_requises | The customer would be created, but the business's terms are not accepted |
Warning : always give a reference (the receipt number): a POS that retries after a connection drop does not add two stamps. A reference whose visit was cancelled cannot be used again.
Updated
Was this page helpful?Thanks for your feedback.