> For the complete documentation index, see [llms.txt](https://docs.thewalletcrew.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thewalletcrew.io/guides-animation/fr/engage-and-animate/benefit-templates/grant-and-use-benefits.md).

# Accorder et utiliser les avantages

Attribuez des avantages aux cartes Wallet depuis la console, les automatisations, les cartes à tampons ou l’API, utilisez-les avec Scanner de Carte et suivez-les dans les analyses.

A [modèle d'avantage](https://docs.thewalletcrew.io/guides-animation/fr/engage-and-animate/benefit-templates.md) ne devient utile que lorsqu'il est attribué à des Cartes. Cette page couvre toutes les façons dont un avantage atteint une Carte, comment le personnel et la console d'administration l'utilisent, et comment suivre ses performances.

## Façons d'attribuer un avantage

| Canal               | Idéal pour                                                                                                                                       | Où le configurer                                                                                                                                                                                                                                                |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Console**         | Une Carte à la fois : tests, gestes de service client.                                                                                           | Page de la Carte → **Avantages** → **Attribuer un avantage**.                                                                                                                                                                                                   |
| **Automatisation**  | Campagnes et règles appliquées à de nombreuses Cartes : cadeaux de bienvenue, anniversaires, montées de niveau, audiences à maintenir engagées.  | [Automatisation](https://docs.thewalletcrew.io/guides-animation/fr/engage-and-animate/automatisation.md) avec l' **Attribuer un avantage** action.                                                                                                              |
| **Carte à tampons** | Récompenses obtenues en collectant des tampons.                                                                                                  | **modèle d'avantage de récompense** sur une [modèle de carte à tampons](https://docs.thewalletcrew.io/guides-design/fr/conception/stamp-card.md).                                                                                                               |
| **API**             | Attributions pilotées par un CRM, un moteur de fidélité, un POS ou une plateforme e-commerce.                                                    | [API des avantages](https://docs.thewalletcrew.io/api-reference/pass-management/benefits.md).                                                                                                                                                                   |
| **Fichier groupé**  | Grosses attributions ponctuelles à partir d'un fichier.                                                                                          | colonne Modèle d'avantage du [mise à jour de Carte par fichier plat](https://docs.thewalletcrew.io/configure/fr/advanced-configuration/wallet/import-and-export/update-pass-using-flat-files.md).                                                               |
| **Connecteurs**     | Avantages qui existent déjà dans un système partenaire, comme des coupons d'une plateforme de fidélité, ou un script de fournisseur d'avantages. | Paramètres du connecteur, par exemple [Comarch](https://docs.thewalletcrew.io/connectors/fr/crm-and-fidelity/comarch.md) ou le [script du fournisseur d'avantages](https://docs.thewalletcrew.io/developers-guides/fr/scripting/endpoints/benefit-provider.md). |

Les avantages envoyés par une intégration sans modèle derrière eux sont affichés comme **Externe** dans la console d'administration.

### Attribuer un avantage depuis la console

L'attribution depuis la page de la Carte est le moyen le plus rapide de tester un modèle ou de faire un geste ponctuel.

{% stepper %}
{% step %}

#### Ouvrez la Carte

Ouvrir **Wallet → Cartes**, trouvez la Carte, puis ouvrez son **Avantages** onglet.
{% endstep %}

{% step %}

#### Choisissez le modèle d'avantage

Cliquez sur **Attribuer un avantage**, recherchez le modèle par son nom et sélectionnez-le. Le nom interne s'affiche en gris sous le titre. Les modèles déjà sur la Carte, ou pas encore utilisables, peuvent quand même être attribués et sont seulement signalés ; les modèles expirés sont affichés grisés car le titulaire recevrait un avantage expiré. Lorsque le modèle sélectionné est déjà sur la Carte, le bouton affiche **Actualiser l'avantage**: l'attribuer à nouveau met à jour l'avantage existant issu du modèle au lieu d'en ajouter un second.
{% endstep %}

{% step %}

#### Confirmez

Cliquez sur **Attribuer un avantage**. La Carte est mise à jour immédiatement dans le Wallet du titulaire.
{% endstep %}
{% endstepper %}

<figure><img src="https://3130570494-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F97ZAXMtqOjhvBBCfpmcE%2Fuploads%2Fgit-blob-6019a0ee02171b24016ccd70b915c03324d7ae4a%2Fpass-grant-a-benefit-dialog-retake.png?alt=media" alt="The Grant a benefit dialog shows each template&#x27;s behavior and validity, marks those already on the pass, and offers Refresh benefit for one the pass already holds."><figcaption><p>La boîte de dialogue Attribuer un avantage affiche le comportement et la validité de chaque modèle, marque ceux déjà sur la Carte et propose Actualiser l'avantage pour celui que la Carte contient déjà.</p></figcaption></figure>

{% hint style="info" %}
Quand aucun modèle n'est proposé, créez-en un d'abord ou remettez-en un existant sur **Actif**. Lorsque la Carte comporte déjà 20 avantages actifs, supprimez un avantage expiré avant d'en attribuer un nouveau. Voir [Limites](https://docs.thewalletcrew.io/guides-animation/fr/engage-and-animate/benefit-templates.md#limits).
{% endhint %}

### Attribuer un avantage avec une automatisation

L' **Attribuer un avantage** action attribue un modèle à chaque Carte ciblée par l'automatisation, dans la même mise à jour que les autres actions de l'automatisation (changement de données, thème, modèle de Carte), suivie de la notification lorsqu'il y en a une. Un modèle désactivé ou supprimé au moment où l'automatisation s'exécute est ignoré.

Les automatisations peuvent aussi réagir aux événements liés aux avantages (**Un avantage est utilisé**, **Un avantage est crédité**, **Le solde d'un avantage évolue dans un sens ou dans l'autre**). Voir [Automatisation](https://docs.thewalletcrew.io/guides-animation/fr/engage-and-animate/automatisation.md) la référence complète.

### Attribuer un avantage via l'API

Les intégrations attribuent un modèle à une Carte, ou créent un avantage autonome, avec l'API des avantages. L'attribution d'un modèle est idempotente : attribuer à nouveau le même modèle à la même Carte met à jour l'avantage qu'il a déjà créé.

| Opération                                  | Point de terminaison                                                        |
| ------------------------------------------ | --------------------------------------------------------------------------- |
| Attribuer un modèle d'avantage à une Carte | `POST /api/{tenantId}/passes/{passId}/benefitTemplates/{benefitTemplateId}` |
| Lister les avantages d'une Carte           | `GET /api/{tenantId}/passes/{passId}/benefits`                              |
| Créer un avantage sur une Carte            | `POST /api/{tenantId}/passes/{passId}/benefits`                             |
| Lire, remplacer ou supprimer un avantage   | `GET`, `PUT`, `DELETE /api/{tenantId}/passes/{passId}/benefits/{benefitId}` |
| Enregistrer une utilisation ou un crédit   | `POST /api/{tenantId}/passes/benefits/{benefitId}/movements`                |
| Lister les avantages sur toutes les Cartes | `GET /api/{tenantId}/benefits`                                              |

Une mutation contient une valeur signée `valeur` (négative pour utiliser, positive pour créditer, jamais zéro, nombres entiers uniquement) et l' `ancienneValeur` que l'appelant a lue en dernier. Si le solde a changé entre-temps, la requête est refusée avec un conflit et rien n'est appliqué, donc une requête réessayée ne peut jamais utiliser un avantage deux fois. La référence complète, y compris les autorisations et les erreurs, se trouve dans la [référence de l'API](https://docs.thewalletcrew.io/api-reference/pass-management/benefits.md).

## Gérer un avantage sur une Carte

L' **Avantages** onglet d'une Carte répertorie tous les avantages qu'elle contient, avec leur statut, comportement, utilisations restantes, validité et origine, par exemple **Console**. Chaque ligne comporte un **bouton Utiliser** et un menu pour ouvrir l'avantage.

<figure><img src="https://3130570494-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F97ZAXMtqOjhvBBCfpmcE%2Fuploads%2Fgit-blob-7f2efd0fa8ecbdaaaaec983d939fa9846fb9c12b%2Fpass-benefits-tab-retake.png?alt=media" alt="The Benefits tab of a pass shows each benefit&#x27;s status, behavior, uses left and validity."><figcaption><p>L'onglet Avantages d'une Carte affiche le statut, le comportement, les utilisations restantes et la validité de chaque avantage.</p></figcaption></figure>

Ouvrir un avantage montre d'où il vient, son historique d'utilisation et les actions disponibles.

| Action                                          | Effet                                                                                                                                                                         |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Compter 1 utilisation** / **bouton Utiliser** | Enregistre une utilisation, par exemple lorsque l'avantage a été utilisé à une caisse sans Carte Scanner.                                                                     |
| **Rendre 1 utilisation**                        | Crédite une utilisation après une erreur. Un avantage à usage unique ou à usages multiples ne peut jamais dépasser son nombre initial d'utilisations.                         |
| **Ajuster le solde**                            | Enregistre une entrée signée, positive pour créditer et négative pour déduire, avec un motif. Elle ne peut pas faire passer l'avantage sous zéro et ne peut pas être annulée. |
| **Modifier** le code                            | Remplace uniquement le code de cet avantage.                                                                                                                                  |
| **Prolonger**                                   | Modifie la validité pour ce titulaire uniquement, sans modifier le modèle.                                                                                                    |
| **Retirer de la Carte**                         | Supprime l'avantage de la Carte et libère son emplacement.                                                                                                                    |

Le titre, la description, le visuel et les liens d'un avantage unique sont copiés depuis le modèle lorsqu'il est attribué. Ils ne peuvent pas être modifiés sur une Carte : attribuer à nouveau le modèle les actualise.

<figure><img src="https://3130570494-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F97ZAXMtqOjhvBBCfpmcE%2Fuploads%2Fgit-blob-45d78c1f19103d5ddcf167595dd64173919c516c%2Fpass-benefit-detail-page-retake.png?alt=media" alt="A benefit&#x27;s page shows its origin, its usage history and the actions to give back, adjust, change the code or extend it."><figcaption><p>La page d'un avantage affiche son origine, son historique d'utilisation et les actions pour le rendre, l'ajuster, modifier le code ou le prolonger.</p></figcaption></figure>

## Utiliser un avantage au comptoir

[Carte Scanner](https://docs.thewalletcrew.io/guides-scan/fr/scanner/pass-scanner.md) répertorie les avantages d'une Carte scannée qui ont **Afficher dans Carte Scanner** activé, et le personnel en touche un pour l'utiliser. Un [profil Carte Scanner](https://docs.thewalletcrew.io/guides-scan/fr/scanner/pass-scanner/pass-scanner-profiles.md) peut restreindre la liste à certains tags ou modèles, par exemple uniquement les avantages du bar sur le téléphone du bar. Avec **Utiliser automatiquement à la lecture**, chaque scan utilise l'avantage immédiatement, sans toucher, ce qui accélère les files d'attente dans un bar ou un vestiaire.

Chaque utilisation est enregistrée avec sa source (console, Carte Scanner, API), l'opérateur ou la clé API et l'appareil, et apparaît dans l'historique d'utilisation de l'avantage.

{% hint style="warning" %}
Une utilisation effectuée dans Carte Scanner est définitive au comptoir. Pour corriger une erreur, ouvrez la Carte dans la console d'administration et utilisez **Rendre 1 utilisation**. L'historique conserve les deux entrées, afin que les rapports restent exacts.
{% endhint %}

## Suivre les avantages

**Analytique → Avantages** indique les performances des avantages sur une période choisie : consultez [Tableaux de bord d'analytique](https://docs.thewalletcrew.io/guides-monitoring/fr/monitor/analytics-dashboards.md#benefits).

Le taux d'utilisation divise les utilisations par les avantages attribués. Un modèle à usages multiples ou illimités peut donc dépasser 100 % : un pack « 5 ateliers barista » utilisé trois fois affiche 300 %.

<figure><img src="https://3130570494-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F97ZAXMtqOjhvBBCfpmcE%2Fuploads%2Fgit-blob-0c9e6f9d9155bd63544a87a0a6d381b984627528%2Fanalytics-benefits-dashboard.png?alt=media" alt="Benefit analytics shows uses, engaged passes and new benefits, with the top benefit templates of the period."><figcaption><p>L'analytique des avantages montre les utilisations, les Cartes engagées et les nouveaux avantages, avec les principaux modèles d'avantages de la période.</p></figcaption></figure>

Chaque modification est aussi un événement qui peut être interrogé avec l' [API Insights](https://docs.thewalletcrew.io/developers-guides/fr/integration-guides/insights-api.md) ou envoyé à d'autres outils avec [des webhooks](https://docs.thewalletcrew.io/developers-guides/fr/integration-guides/webhooks.md). Les événements d'un avantage sur une Carte sont listés dans la [référence des événements](https://docs.thewalletcrew.io/guides-monitoring/fr/monitor/what-the-wallet-crew-tracks.md#event-reference). Les événements de modèle sont :

| Événement                                                                       | Quand                                                                     |
| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| `BenefitTemplate:Created`, `BenefitTemplate:Updated`, `BenefitTemplate:Deleted` | Un modèle est créé, modifié ou supprimé dans la console d'administration. |

### Afficher les avantages dans les champs de la Carte

Les modèles de Carte peuvent afficher les données d'avantages dans leurs champs avec Liquid. Chaque avantage est disponible sous `benefits.<template key>`, où la clé est l'identifiant du modèle d'avantage avec chaque caractère autre qu'une lettre, un chiffre ou un tiret bas remplacé par `_`benefitStats `Variable`.

| Valeur                                                                                  | {{ benefits.free\_drink\_reward.data.value }}                         |
| --------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| `{{ benefits.free_drink_reward.data.value }}`                                           | Le solde de l'avantage attribué depuis le modèle `free-drink-reward`. |
| `{{ benefitStats.total }}`                                                              | Avantages sur la Carte, hors avantages supprimés.                     |
| `{{ benefitStats.active }}`                                                             | Avantages utilisables maintenant.                                     |
| `{{ benefitStats.scheduled }}`, `{{ benefitStats.used }}`, `{{ benefitStats.expired }}` | Avantages pas encore actifs, utilisés ou expirés.                     |

Voir [templating Liquid](https://docs.thewalletcrew.io/developers-guides/fr/integration-guides/wallet/templating-engine.md) pour la syntaxe.

## Migrer depuis l'API des privilèges

Les anciens points de terminaison de privilèges sont obsolètes et redirigent vers les avantages. Le mappage complet des anciens noms et des noms actuels se trouve dans [Migrer depuis l'API des privilèges](https://docs.thewalletcrew.io/developers-guides/fr/integration-guides/wallet/pass-lifecycle.md#migrate-from-the-privilege-api) dans les guides des développeurs.

## FAQ

<details>

<summary><strong>Pourquoi l'avantage n'a-t-il pas été attribué par l'automatisation ?</strong></summary>

Vérifiez d'abord l'historique d'exécution de l'automatisation. Un modèle inactif ou supprimé au moment où l'automatisation s'exécute est ignoré, et une Carte à la [limite de 20 avantages](https://docs.thewalletcrew.io/guides-animation/fr/engage-and-animate/benefit-templates.md#limits) ne peut pas recevoir un nouvel avantage. Vérifiez aussi que la Carte correspondait bien à l'audience de l'automatisation à ce moment-là.

</details>

<details>

<summary><strong>Attribuer deux fois le même modèle crée-t-il deux avantages ?</strong></summary>

Non. Attribuer un modèle à une Carte qui possède déjà un avantage issu de ce modèle met à jour cet avantage et actualise son titre, sa description, son visuel et ses liens.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.thewalletcrew.io/guides-animation/fr/engage-and-animate/benefit-templates/grant-and-use-benefits.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
