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 en leur nom peuvent configurer et gérer des programmes de fidélité de manière programmatique à l'aide de LoyaltyProgramService. Ce service vous permet de créer, de récupérer, de lister, de modifier et de supprimer des programmes de fidélité.

Important : Ce service n'est disponible que pour certains marchands. Contactez l'équipe d'assistance pour exprimer votre intérêt en envoyant une demande d'ajout à 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 du règlement, consultez À propos du programme de fidélité des marchands dans le centre d'aide Merchant Center.

Concepts clés

Tenez compte des concepts et limites suivants lorsque vous utilisez des programmes de fidélité :

• 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 : l'API Merchant 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 sur 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 disposant d'un accès autorisé au compte d'un marchand peuvent gérer le programme pour le compte du marchand.
• Examen éditorial : après avoir créé ou mis à jour un programme de fidélité, celui-ci est examiné. Le champ review_result.review_status indique si le programme est UNDER_REVIEW, APPROVED ou REJECTED.
• Régions prises en charge : les programmes de fidélité des marchands sont disponibles dans les pays suivants : Allemagne, Australie, Brésil, Canada, Corée du Sud, Espagne, États-Unis, France, Inde, Italie, Mexique, Pays-Bas et Royaume-Uni.
• Conditions d'accès aux niveaux : l'accès aux niveaux peut être sans frais, nécessiter des frais d'adhésion, un seuil de dépenses ou une carte de crédit de la marque du marchand. Les niveaux basés sur la profession (par exemple, étudiant ou militaire) ne sont pas acceptés.
• Avantages : les programmes incluent la livraison gratuite, des points de fidélité et des prix réservés aux membres. Dans les annonces, le prix réservé aux membres nécessite une remise d'au moins 5 % ou 5 unités de devise par rapport 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 programme de fidélité tiers).
• Activez le module complémentaire du programme de fidélité pour votre compte. Vous pouvez activer le module complémentaire à l'aide de l'une des options suivantes :
  • UI Merchant Center : suivez les instructions de la section Configurer un programme de fidélité de l'aide Merchant Center.
  • Sous-API Programs : activez le programme de manière programmatique, comme décrit dans Activer des 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 détails tels que la description du programme, l'URL d'inscription et les niveaux du programme, avec leurs avantages et exigences uniques.

Le champ obligatoire program_label définit l'identifiant unique du programme de fidélité. Par exemple, fournir l'étiquette my-rewards génère 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, utilisez la méthode loyaltyPrograms.get.

Remarque : Même si le module complémentaire de 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 votre ID de 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 les programmes associés à des sous-comptes. Même si le module complémentaire du 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"
      ]
    }
  ]
}

Mettre à jour 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 l'intégralité de la liste existante. Pour éviter toute perte de données involontaire, envoyez d'abord une requête get pour récupérer les valeurs actuelles avant de mettre à jour les champs répétés.

Mise à jour partielle avec 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é pour une personnalisation naturelle dans la recherche Google, consultez le guide du service ciblage par liste de clients pour les programmes de fidélité.
• Pour activer ou désactiver des programmes Shopping pour votre compte, consultez le guide de la sous-API Programs.
• Pour en savoir plus sur la configuration de l'établissement, les règles éditoriales et les rapports, consultez À propos du programme de fidélité des marchands dans le centre d'aide Merchant Center.
• Pour explorer les méthodes d'API et les définitions de ressources, consultez la documentation de référence de l'API Merchant.