Créer un client
/v1/customers
Crée un client et renvoie sa fiche complète. L'identifiant du nouveau client est dans data.id : conservez-le, c'est lui qui permet de relire ou de modifier ce client ensuite. Aucun champ n'est obligatoire à lui seul, mais il faut renseigner au moins un de ces champs : nom, prenom, nom_2, email, mobile, tel. Les champs absents prennent leur valeur par défaut.
Si un client actif porte déjà l'adresse mail envoyée, la création est refusée avec l'erreur duplicate_email, qui donne les identifiants des clients existants. Ne contournez pas ce refus par réflexe : dans la plupart des cas, il faut modifier le client existant avec PATCH /v1/customers/{id}. Si ce sont bien deux personnes différentes qui partagent une adresse mail, renvoyez la requête avec ?allow_duplicate_email=true. Il n'existe pas d'appel « créer ou mettre à jour » : une adresse mail n'étant pas unique dans Wanapos, l'API ne choisit jamais à votre place quelle fiche modifier.
Les accords de communication news_sms et news_email valent false s'ils ne sont pas envoyés : n'envoyez true que si la personne a réellement donné son accord pour recevoir des SMS ou des mails. fidelite_active vaut true s'il n'est pas envoyé. La fidélité (points, cumuls), les dates et l'identifiant ne s'écrivent pas par cette adresse : les points s'ajustent par POST /v1/customers/{id}/loyalty-points.
Pour ne jamais créer deux fois le même client après une coupure réseau, envoyez un en-tête Idempotency-Key. Pour vérifier une requête sans rien enregistrer, ajoutez ?dry_run=true.
Paramètres
dry_run |
Facultatif | true pour tout vérifier sans rien enregistrer : la réponse est celle que vous auriez obtenue, avec meta.dry_run à true. L'identifiant renvoyé n'est alors pas réservé. |
allow_duplicate_email |
Facultatif | true pour enregistrer même si un autre client actif porte déjà cette adresse mail. À n'utiliser qu'après avoir vérifié qu'il s'agit bien de deux personnes différentes. |
Idempotency-Key |
Facultatif | Identifiant unique de votre choix (8 à 100 caractères). Si vous renvoyez la même requête avec le même identifiant, elle n'est pas exécutée deux fois : vous recevez la réponse d'origine. Recommandé pour toute création. |
Corps JSON à envoyer
| Champ | Type | Description |
|---|---|---|
civilite |
texte |
Civilité, parmi les valeurs exactes : chaîne vide, M., Mme, Mlle, Sct. À la création, si elle est absente : la civilité par défaut réglée par le commerçant. |
nom |
texte | Nom. 40 caractères au maximum. |
prenom |
texte | Prénom. 40 caractères au maximum. |
nom_2 |
texte | Nom secondaire, facultatif. Chaîne vide si non renseigné. 40 caractères au maximum. |
email |
texte | Adresse mail. Chaîne vide si non renseignée. Elle n'est pas unique : plusieurs clients peuvent porter la même. 50 caractères au maximum. |
tel |
texte | Téléphone fixe. 17 caractères au maximum. |
mobile |
texte | Téléphone mobile. 17 caractères au maximum. |
bc_ext |
texte | Code-barres associé au client (carte de fidélité par exemple). 32 caractères au maximum. |
remise_pc |
entier | Remise permanente accordée au client, en pourcentage. Entier de 0 à 100. |
notes |
texte | Notes libres saisies par le commerçant. 5 000 caractères au maximum. |
libre_1 |
texte |
Champ personnalisé texte n° 1. Son libellé est dans champs_personnalises. 50 caractères au maximum. |
libre_2 |
texte | Champ personnalisé texte n° 2. 50 caractères au maximum. |
libre_3 |
texte | Champ personnalisé texte n° 3. 50 caractères au maximum. |
custom_io_1 |
booléen | Champ personnalisé oui/non n° 1. |
custom_io_2 |
booléen | Champ personnalisé oui/non n° 2. |
custom_io_3 |
booléen | Champ personnalisé oui/non n° 3. |
custom_date_1 |
texte |
Champ personnalisé date n° 1 (AAAA-MM-JJ). Chaîne vide si non renseignée. Format AAAA-MM-JJ. Chaîne vide pour effacer la date. |
custom_date_2 |
texte |
Champ personnalisé date n° 2. Format AAAA-MM-JJ. Chaîne vide pour effacer la date. |
custom_date_3 |
texte |
Champ personnalisé date n° 3. Format AAAA-MM-JJ. Chaîne vide pour effacer la date. |
news_sms |
booléen |
Le client accepte de recevoir des SMS. À respecter avant tout envoi. false à la création si absent : n'envoyez true que si la personne a donné son accord. |
news_email |
booléen |
Le client accepte de recevoir des mails. À respecter avant tout envoi. false à la création si absent : n'envoyez true que si la personne a donné son accord. |
fidelite_active |
booléen |
Le client participe au programme de fidélité. true à la création si absent. |
id_shop_origin |
entier |
Identifiant du magasin d'origine du client, parmi ceux listés par GET /v1/me. À la création, si absent : le premier magasin du compte. |
adresse |
objet | Adresse postale. Seuls les champs envoyés sont enregistrés ou modifiés. |
adresse.ligne1 |
texte | Adresse. 50 caractères au maximum. |
adresse.ligne2 |
texte | Complément d'adresse. 50 caractères au maximum. |
adresse.cp |
texte | Code postal. 9 caractères au maximum. |
adresse.ville |
texte | Ville. 30 caractères au maximum. |
adresse.pays_code |
texte |
Code du pays à deux lettres (FR, BE, CH…). À la création, si absent : le pays du magasin d'origine. |
adresse.tva_intra |
texte | Numéro de TVA intracommunautaire. 32 caractères au maximum. |
Exemple d'appel
curl -X POST "https://api.wanapos.com/v1/customers" \
-H "Authorization: Bearer VOTRE_CLE" \
-H "Content-Type: application/json" \
-d '{"email":"claire.martin@exemple.com","nom":"Martin","prenom":"Claire","civilite":"Mme","mobile":"0600000000","news_email":true,"adresse":{"ligne1":"12 rue des Lilas","cp":"69003","ville":"Lyon","pays_code":"FR"}}'
Réponse en cas de succès (statut 201)
Le client créé, avec sa fiche complète.
| Champ | Type | Description |
|---|---|---|
data |
objet |
Un client du compte. Les noms de champs sont ceux des événements sortants client_create et client_update. Voir tous les champs
|
meta |
objet | |
meta.request_id |
texte | Identifiant de l'appel, à communiquer à l'assistance en cas de problème. |
{
"data": {
"id": 1842,
"civilite": "Mme",
"nom": "Martin",
"prenom": "Claire",
"nom_2": "",
"email": "claire.martin@exemple.com",
"tel": "",
"mobile": "0600000000",
"bc_ext": "",
"remise_pc": 0,
"notes": "",
"libre_1": "",
"libre_2": "",
"libre_3": "",
"custom_io_1": false,
"custom_io_2": false,
"custom_io_3": false,
"custom_date_1": "",
"custom_date_2": "",
"custom_date_3": "",
"news_sms": false,
"news_email": true,
"fidelite_active": true,
"actif": true,
"id_shop_origin": 1,
"date_creation": "2026-03-14T10:22:00+01:00",
"date_update": "2026-10-02T16:05:00+02:00",
"adresse": {
"ligne1": "12 rue des Lilas",
"ligne2": "",
"cp": "69003",
"ville": "Lyon",
"id_pays": 63,
"pays_code": "FR",
"pays": "France",
"tva_intra": "",
"archived": false
},
"fidelite": {
"points_actuels": 120,
"points_cumules": 340,
"nb_fois_pts_utilises": 2,
"last_pts_acquis": 15,
"total_ca": 412.5,
"total_qt": 17,
"total_pa": 9
},
"champs_personnalises": [
{
"cle": "libre_1",
"libelle": "Customisé 1",
"type": "texte",
"affiche": false,
"valeur": ""
},
{
"cle": "libre_2",
"libelle": "Customisé 2",
"type": "texte",
"affiche": false,
"valeur": ""
},
{
"cle": "libre_3",
"libelle": "Customisé 3",
"type": "texte",
"affiche": false,
"valeur": ""
},
{
"cle": "custom_io_1",
"libelle": "Customisé 1",
"type": "oui_non",
"affiche": false,
"valeur": false
},
{
"cle": "custom_io_2",
"libelle": "Customisé 2",
"type": "oui_non",
"affiche": false,
"valeur": false
},
{
"cle": "custom_io_3",
"libelle": "Customisé 3",
"type": "oui_non",
"affiche": false,
"valeur": false
},
{
"cle": "custom_date_1",
"libelle": "Customisé 1",
"type": "date",
"affiche": false,
"valeur": ""
},
{
"cle": "custom_date_2",
"libelle": "Customisé 2",
"type": "date",
"affiche": false,
"valeur": ""
},
{
"cle": "custom_date_3",
"libelle": "Customisé 3",
"type": "date",
"affiche": false,
"valeur": ""
}
]
},
"meta": {
"request_id": "3f9a1c0b7d2e4a61"
}
}
Erreurs possibles
-
401
Clé absente, inconnue ou révoquée. Codes :
missing_key,invalid_key. -
403
Appel refusé pour ce compte ou cette clé. Codes :
api_not_activated,account_not_eligible,access_blocked,missing_scope. -
409
Un client actif porte déjà cette adresse mail. Code :
duplicate_email. Le message etdetailsdonnent les identifiants des clients existants. Rien n'a été enregistré. -
422
Données envoyées invalides. Code :
validation_failed. Le champdetailsliste chaque erreur. -
429
Quota dépassé. Codes :
rate_limited,daily_quota_exceeded,too_many_failed_attempts. L'en-têteRetry-Afterindique combien de secondes attendre. -
503
Une autre écriture est en cours sur ce compte. Code :
account_busy. Renvoyer la même requête après le délai de l'en-têteRetry-After.
Une question ? contact@wanapos.com
