Présentation des codes promotionnels et des remises

Ce guide explique comment gérer les codes promotionnels et les remises dans le processus de paiement de l'Universal Commerce Protocol (UCP).

Lorsqu'un utilisateur lance une session de paiement, Google fournit des données de promotions provenant de plusieurs sources. Votre intégration doit valider ces promotions en temps réel et renvoyer une répartition précise des remises pour chaque élément. Pour recevoir des codes de réduction, vous devez signaler la prise en charge des remises dans votre profil UCP.

Sources des promotions

Google fournit des données de promotions provenant de deux sources principales :

  • Promotions appliquées automatiquement : offres importées directement depuis vos flux Google Merchant Center. Google applique automatiquement ces offres au panier.
  • Promotions appliquées par l'utilisateur : codes promotionnels que les utilisateurs saisissent manuellement lors du paiement, comme les codes de remise publics ou les offres personnalisées par e-mail. L'interface de paiement accepte jusqu'à 10 codes promotionnels par session.

Implémentation de Checkout API

Lorsqu'un utilisateur crée une session de paiement ou modifie un code promotionnel, Google envoie une requête à vos points de terminaison POST /checkout-sessions ou PUT /checkout-sessions/{id}.

Votre intégration s'appuie sur trois tableaux principaux pour gérer les remises :

  • Codes demandés (discounts.codes) : Google envoie les codes promotionnels de l'utilisateur dans ce tableau. Vous devez renvoyer ce tableau dans votre réponse pour conserver l'état. L'index du tableau de la réponse permet de faire correspondre les avertissements de validation aux codes correspondants.
    • Sémantique de remplacement : l'envoi de ce tableau remplace tous les codes précédemment envoyés.
    • Suppression des codes : l'envoi d'un tableau vide ([]) supprime tous les codes promotionnels.
    • Non sensible à la casse : votre logique métier doit correspondre aux codes sans tenir compte de la casse.
  • Remises appliquées (discounts.applied) : si un code est valide, incluez-le dans ce tableau, avec un title lisible, le amount positif de la remise et la method de calcul.
  • Refus (messages) : si un code n'est pas valide, omettez-le du tableau applied et indiquez le motif de l'échec à l'aide d'un avertissement canonique dans le tableau messages.

Invariants mathématiques

Pour garantir l'intégrité des données et un affichage correct des reçus, votre intégration doit respecter les règles mathématiques suivantes, quelle que soit la version d'UCP utilisée :

  • Somme de l'allocation : la somme de allocations[].amount doit être égale à applied_discount.amount.
  • La somme des totaux des lignes : totals[type=items_discount].amount doit être égal à la somme de line_items[].totals[type=items_discount].amount.

Gestion des erreurs et commentaires des utilisateurs

Si un code promotionnel ou une offre de carte cadeau ne sont pas applicables, ou si une offre précédemment appliquée est supprimée, votre API doit renvoyer des codes de motif clairs. Cela permet à Google d'afficher les commentaires appropriés à l'utilisateur.

Les opérations qui modifient le montant total de la commande, ou celui auquel l'utilisateur s'attend, doivent utiliser type: "warning". Cela permet de s'assurer que les erreurs sont signalées à l'utilisateur plutôt que d'être traitées de manière invisible par la plate-forme. Par exemple, si un utilisateur s'attend à bénéficier d'une remise, mais ne l'obtient pas parce que le code a expiré, vous devez l'en informer.

Informations de référence sur les codes d'erreur

Renvoyez les codes d'erreur canoniques suivants dans le tableau messages de votre réponse. Utilisez "type": "warning" pour indiquer l'éligibilité aux promotions :

Code d'erreur Description
discount_code_expired Le code a expiré.
discount_code_invalid Le code est introuvable ou son format est incorrect.
discount_code_already_applied Le code est déjà appliqué.
discount_code_combination_disallowed Le code n'est pas cumulable avec une autre remise active, ou une limite spécifique au magasin a été atteinte.
discount_code_user_not_logged_in Le code nécessite un utilisateur authentifié.
discount_code_user_ineligible L'utilisateur ne répond pas aux critères d'éligibilité.

Étapes suivantes

Consultez les charges utiles de l'API et les détails techniques de l'implémentation pour votre version d'UCP :

Précédent
Association de l'identité – OAuth 2.0