Présentation des programmes de fidélité

Mettez en avant les avantages de votre magasin sur Google grâce aux programmes de fidélité. Vous pouvez indiquer différents avantages, comme la livraison gratuite, des points à utiliser et des tarifs réservés aux membres. Les avantages de votre programme de fidélité peuvent apparaître dans les fiches gratuites, les annonces Shopping et les annonces produits en magasin sur les surfaces Google, y compris la recherche Google, l'onglet "Shopping" et Google Wallet.

Grâce à l'API Merchant, les marchands et les fournisseurs de programmes de fidélité tiers agissant pour le compte des marchands peuvent configurer et gérer les programmes de fidélité par programmation à l'aide de LoyaltyProgramService. Ce service vous permet de créer, récupérer, lister, mettre à jour et supprimer des programmes de fidélité.

Important : Ce service n'est disponible que pour certains marchands. Contactez l'équipe d'assistance pour demander à participer en envoyant une demande d'inscription sur la liste d'autorisation dans le formulaire d'assistance de l'API Shopping, sous Quel est le problème/la question ? > Demande d'ajout à la liste d'autorisation > Autre.

Pour en savoir plus sur les exigences commerciales et les consignes relatives aux règles, consultez À propos des programmes de fidélité des marchands dans le centre d'aide Merchant Center.

Concepts clés

Lorsque vous utilisez des programmes de fidélité, tenez compte des concepts et des limites suivants :

• Identifiant au niveau du compte : l'API Merchant identifie les programmes de fidélité par l'ID du compte Merchant Center propriétaire.
• Limite d'un seul programme : Merchant API n'accepte qu'un seul programme de fidélité par compte marchand.
• Propriété directe du compte : les programmes de fidélité doivent être configurés directement dans le compte marchand cible (accounts/{ACCOUNT_ID}). Le service ne permet pas de gérer les programmes de fidélité au niveau d'un compte avancé pour les sous-comptes. Les fournisseurs de programmes de fidélité tiers ayant un accès autorisé au compte d'un marchand peuvent gérer le programme en son nom.
• Examen éditorial : une fois que vous avez créé ou mis à jour un programme de fidélité, il est examiné. Le champ review_result.review_status indique si le programme est UNDER_REVIEW, APPROVED ou REJECTED.
• Régions acceptées : les programmes de fidélité des marchands sont disponibles dans les pays acceptés, y compris l'Allemagne, l'Australie, le Brésil, le Canada, la Corée du Sud, l'Espagne, les États-Unis, la France, l'Inde, l'Italie, le Mexique, les Pays-Bas et le Royaume-Uni.
• Conditions d'accès aux niveaux : l'accès aux niveaux peut être sans frais, nécessiter des frais d'adhésion ou un seuil de dépenses, ou exiger une carte de crédit à la marque du marchand. Les niveaux basés sur la profession (comme les niveaux étudiant ou militaire) ne sont pas acceptés.
• Avantages : les programmes sont compatibles avec la livraison gratuite, les points échangeables et les tarifs réservés aux membres. Dans les annonces, le prix réservé aux membres doit être inférieur d'au moins 5% ou 5 unités monétaires au prix standard ou au prix soldé.

Prérequis

Avant de gérer des programmes de fidélité avec l'API Merchant, assurez-vous de remplir les conditions suivantes :

• Vous devez disposer d'un compte Merchant Center actif (ou d'un accès autorisé au compte du marchand si vous êtes un fournisseur de fidélité tiers).
• Activez le module complémentaire Programme de fidélité pour votre compte. Vous pouvez activer le module complémentaire à l'aide de l'une des options suivantes :
  • Interface utilisateur Merchant Center : suivez les instructions de Configurer un programme de fidélité dans l'aide Merchant Center.
  • Sous-API Programs : activez le programme par programmation, comme décrit dans Activer les programmes dans la sous-API Programs.

Voici un exemple de requête permettant d'activer le module complémentaire du programme de fidélité à l'aide de la sous-API Programs :

HTTP

POST https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty:enable

cURL

curl --request POST \
  'https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty:enable?key={YOUR_API_KEY}' \
  --header 'Authorization: Bearer {YOUR_ACCESS_TOKEN}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{}' \
  --compressed

Méthodes

Gérez les programmes de fidélité à l'aide des méthodes suivantes :

• loyaltyPrograms.create
• loyaltyPrograms.get
• loyaltyPrograms.list
• loyaltyPrograms.update
• loyaltyPrograms.delete

Créer un programme de fidélité

Pour créer un programme de fidélité pour un compte, utilisez la méthode loyaltyPrograms.create. Spécifiez des informations telles que les descriptions du programme, l'URL d'inscription et les niveaux du programme avec leurs avantages et exigences uniques.

L'élément program_label obligatoire définit l'identifiant unique du programme de fidélité. Par exemple, si vous fournissez le libellé my-rewards, vous obtenez une ressource name de accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards.

Voici un exemple de requête :

HTTP

POST https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms

{
  "programLabel": "my-rewards",
  "loyaltyProgram": {
    "programName": "my rewards",
    "tiers": [
      {
        "tierName": "gold",
        "tierLabel": "gold",
        "tierBenefits": [
          {
            "otherBenefit": "free gift on your birthday"
          },
          {
            "structuredBenefit": {
              "pointsEarningBenefit": {
                "minimumMoneySpent": {
                  "currencyCode": "USD",
                  "units": "25"
                },
                "pointsEarningBenefitAnnotation": {
                  "pointsEarned": 1.0,
                  "amountSpent": {
                    "currencyCode": "USD",
                    "units": "1"
                  }
                }
              }
            }
          }
        ],
        "requirements": {
          "freeToJoin": true
        }
      }
    ],
    "programDescriptions": [
      "earn rewards buying products you love"
    ],
    "signupUrl": "https://www.example.com/my_rewards_signup",
    "regionCodes": [
      "US"
    ]
  }
}

Remplacez {ACCOUNT_ID} par l'identifiant unique de votre compte Merchant Center.

Voici un exemple de réponse à une requête réussie :

{
  "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
  "programName": "my rewards",
  "tiers": [
    {
      "tierName": "gold",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "free gift on your birthday"
        },
        {
          "structuredBenefit": {
            "pointsEarningBenefit": {
              "minimumMoneySpent": {
                "currencyCode": "USD",
                "units": "25"
              },
              "pointsEarningBenefitAnnotation": {
                "pointsEarned": 1.0,
                "amountSpent": {
                  "currencyCode": "USD",
                  "units": "1"
                }
              }
            }
          }
        }
      ],
      "requirements": {
        "freeToJoin": true
      },
      "signupUrl": "https://www.example.com/my-rewards/gold"
    }
  ],
  "programDescriptions": [
    "earn rewards buying products you love"
  ],
  "signupUrl": "https://www.example.com/my_rewards_signup",
  "reviewResult": {
    "reviewStatus": "UNDER_REVIEW"
  },
  "regionCodes": [
    "US"
  ]
}

Récupérer un programme de fidélité

Pour récupérer les détails d'un programme de fidélité spécifique dont vous êtes propriétaire, utilisez la méthode loyaltyPrograms.get.

Remarque : Même si le module complémentaire Programme de fidélité n'a pas été activé, ce point de terminaison répond toujours avec un programme de fidélité correspondant sans renvoyer d'erreur.

Voici un exemple de requête :

HTTP

GET https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/{PROGRAM_LABEL}

Remplacez {ACCOUNT_ID} par l'ID de votre compte et {PROGRAM_LABEL} par le libellé unique du programme de fidélité (par exemple, my-rewards).

Voici un exemple de réponse à une requête réussie :

{
  "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
  "programName": "my rewards",
  "tiers": [
    {
      "tierName": "gold",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "free gift on your birthday"
        },
        {
          "structuredBenefit": {
            "pointsEarningBenefit": {
              "minimumMoneySpent": {
                "currencyCode": "USD",
                "units": "25"
              },
              "pointsEarningBenefitAnnotation": {
                "pointsEarned": 1.0,
                "amountSpent": {
                  "currencyCode": "USD",
                  "units": "1"
                }
              }
            }
          }
        }
      ],
      "requirements": {
        "freeToJoin": true
      },
      "signupUrl": "https://www.example.com/my-rewards/gold"
    }
  ],
  "programDescriptions": [
    "earn rewards buying products you love"
  ],
  "signupUrl": "https://www.example.com/my_rewards_signup",
  "reviewResult": {
    "reviewStatus": "UNDER_REVIEW"
  },
  "regionCodes": [
    "US"
  ]
}

Lister les programmes de fidélité

Pour lister tous les programmes de fidélité dont vous êtes propriétaire et qui sont associés à votre compte, utilisez la méthode loyaltyPrograms.list.

Remarque : Cette méthode ne liste que les programmes de fidélité appartenant directement au compte spécifié, et non ceux associés aux sous-comptes. Même si le module complémentaire Programme de fidélité est désactivé, ce point de terminaison répond avec les programmes existants sans renvoyer d'erreur.

Voici un exemple de requête :

HTTP

GET https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms

Voici un exemple de réponse à une requête réussie :

{
  "loyaltyPrograms": [
    {
      "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
      "programName": "my rewards",
      "tiers": [
        {
          "tierName": "gold",
          "tierLabel": "gold",
          "tierBenefits": [
            {
              "otherBenefit": "free gift on your birthday"
            },
            {
              "structuredBenefit": {
                "pointsEarningBenefit": {
                  "minimumMoneySpent": {
                    "currencyCode": "USD",
                    "units": "25"
                  },
                  "pointsEarningBenefitAnnotation": {
                    "pointsEarned": 1.0,
                    "amountSpent": {
                      "currencyCode": "USD",
                      "units": "1"
                    }
                  }
                }
              }
            }
          ],
          "requirements": {
            "freeToJoin": true
          },
          "signupUrl": "https://www.example.com/my-rewards/gold"
        }
      ],
      "programDescriptions": [
        "earn rewards buying products you love"
      ],
      "signupUrl": "https://www.example.com/my_rewards_signup",
      "reviewResult": {
        "reviewStatus": "UNDER_REVIEW"
      },
      "regionCodes": [
        "US"
      ]
    }
  ]
}

Modifier un programme de fidélité

Pour mettre à jour un programme de fidélité existant, utilisez la méthode loyaltyPrograms.update. Effectuez une mise à jour partielle à l'aide d'un update_mask ou un remplacement complet en omettant le masque.

Important : Lorsque vous mettez à jour un programme de fidélité, les champs répétés (tels que programDescriptions et tiers) ne peuvent pas être mis à jour sur place. Tout champ répété inclus dans une mise à jour remplace la liste existante dans son intégralité. Pour éviter toute perte de données involontaire, envoyez d'abord une requête get afin de récupérer les valeurs actuelles avant de mettre à jour les champs répétés.

Mise à jour partielle avec un masque de mise à jour

Un update_mask vous permet de spécifier les champs exacts à mettre à jour. Seuls les champs listés dans le masque sont modifiés, tandis que les champs non listés restent inchangés. Tout champ omis du masque de mise à jour est ignoré, même s'il est fourni dans le corps de la requête.

L'exemple de requête suivant ne met à jour que programDescriptions et advancedSettings :

HTTP

PATCH https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/{PROGRAM_LABEL}?update_mask=program_descriptions,advanced_settings

{
  "programDescriptions": [
    "a new description of the program"
  ],
  "advancedSettings": {
    "hideDisplayFromNonMembers": true
  },
  "signupUrl": "https://www.example.com"
}

Dans cet exemple, le service ignore signupUrl, car il n'est pas inclus dans update_mask. Le champ programDescriptions remplace complètement toutes les descriptions précédemment configurées.

Voici un exemple de réponse à une requête réussie :

{
  "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
  "programName": "my rewards",
  "tiers": [
    {
      "tierName": "gold",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "free gift on your birthday"
        },
        {
          "structuredBenefit": {
            "pointsEarningBenefit": {
              "minimumMoneySpent": {
                "currencyCode": "USD",
                "units": "25"
              },
              "pointsEarningBenefitAnnotation": {
                "pointsEarned": 1.0,
                "amountSpent": {
                  "currencyCode": "USD",
                  "units": "1"
                }
              }
            }
          }
        }
      ],
      "requirements": {
        "freeToJoin": true
      },
      "signupUrl": "https://www.example.com/my-rewards/gold"
    }
  ],
  "programDescriptions": [
    "a new description of the program"
  ],
  "signupUrl": "https://www.example.com/my_rewards_signup",
  "reviewResult": {
    "reviewStatus": "UNDER_REVIEW"
  },
  "regionCodes": [
    "US"
  ],
  "advancedSettings": {
    "hideDisplayFromNonMembers": true
  }
}

Remplacement complet sans masque de mise à jour

Lorsque vous omettez le paramètre update_mask, la requête remplace complètement la configuration du programme de fidélité.

Voici un exemple de requête :

HTTP

PATCH https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/{PROGRAM_LABEL}

{
  "programName": "Updated Program",
  "signupUrl": "https://example.com/updated",
  "programDescriptions": [
    "Updated description"
  ],
  "regionCodes": [
    "US"
  ],
  "tiers": [
    {
      "tierName": "Gold Tier",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "Free shipping"
        }
      ],
      "requirements": {
        "freeToJoin": true
      }
    }
  ]
}

Voici un exemple de réponse à une requête réussie :

{
  "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
  "programName": "Updated Program",
  "tiers": [
    {
      "tierName": "Gold Tier",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "Free shipping"
        }
      ],
      "requirements": {
        "freeToJoin": true
      }
    }
  ],
  "programDescriptions": [
    "Updated description"
  ],
  "signupUrl": "https://example.com/updated",
  "reviewResult": {
    "reviewStatus": "UNDER_REVIEW"
  },
  "regionCodes": [
    "US"
  ]
}

Supprimer un programme de fidélité

Pour supprimer un programme de fidélité de votre compte, utilisez la méthode loyaltyPrograms.delete.

Voici un exemple de requête :

HTTP

DELETE https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/{PROGRAM_LABEL}

Si la requête aboutit, le corps de la réponse est vide.

Étapes suivantes

• Pour associer des acheteurs individuels aux niveaux de votre programme de fidélité afin de personnaliser les résultats naturels dans la recherche Google, consultez le guide du service de ciblage par liste de clients fidèles.
• Pour activer ou désactiver les programmes d'achat pour votre compte, consultez le guide de la sous-API Programs.
• Pour en savoir plus sur la configuration de l'entreprise, les règles éditoriales et les rapports, consultez À propos du programme de fidélité des marchands dans l'aide Merchant Center.
• Pour explorer les méthodes et les définitions de ressources de l'API, consultez la documentation de référence de Merchant API.