Présentation de l'API Promotions des marchands

Utilisez des promotions pour présenter des offres spéciales pour les produits que vous vendez sur Google. Ces promotions s'affichent sur plusieurs propriétés Google, dont la recherche Google, Shopping et Chrome. Pour être approuvées, les promotions doivent répondre à certains critères. Pour en savoir plus, consultez la section Critères de promotion.

Lorsque vous ajoutez une promotion à vos produits, un lien "offre spéciale" s'affiche. (par exemple, "15% de remise" ou "Livraison gratuite"). Ce type de lien peut accroître l'attractivité de vos produits et inciter les clients à les acheter. Toutes les promotions sont appliquées lors du règlement en ligne ou dans votre point de vente.

Pour en savoir plus, consultez Principes de base des promotions.

Prérequis

Vous devez nous fournir certaines informations concernant votre entreprise et vos produits pour que nous puissions diffuser vos promotions. Vous devez disposer des éléments suivants:

Vous devez également inscrire votre compte marchand au programme des promotions. Si vous ne savez pas si vous êtes déjà inscrit, consultez Merchant Center.

Si ce n'est pas le cas, remplissez le formulaire de demande. L'équipe chargée des promotions vous contactera dès que vous serez prêt à commencer l'implémentation.

Pour en savoir plus, consultez Règles et critères de participation.

Créer une source de données

Vous pouvez utiliser la méthode accounts.dataSources.create pour créer une source de données de promotions. Si une source de données de promotion existante est disponible, utilisez la méthode accounts.dataSources.list pour récupérer toutes les sources de données. Vous pouvez ensuite utiliser le champ name de la source de données des promotions pour créer des promotions.

La requête suivante montre comment créer une source de données pour ajouter des promotions:

POST https://merchantapi.googleapis.com/datasources/v1beta/accounts/{ACCOUNT_ID}/dataSources

{
  "displayName": "{DISPLAY_NAME}",
  "promotionDataSource": {
    "contentLanguage": "{CONTENT_LANGUAGE}",
    "targetCountry": "{TARGET_COUNTRY}"
  }
}

Remplacez les éléments suivants :

  • {ACCOUNT_ID}: identifiant unique de votre compte tel qu'il apparaît dans l'interface utilisateur de Merchant Center.
  • {DISPLAY_NAME}: nom à afficher de la source de données.
  • {CONTENT_LANGUAGE}: code de langue ISO 639-1 à deux lettres des produits de la source de données.
  • {TARGET_COUNTRY}: code de territoire CLDR du pays cible dans lequel vous souhaitez que les promotions soient visibles.

Une fois la requête exécutée, la réponse suivante s'affiche. Elle contient des informations sur la source de données de promotions nouvellement créée:

{
  "name": "accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}",
  "dataSourceId": "{DATASOURCE_ID}",
  "displayName": "{DISPLAY_NAME}",
  "promotionDataSource": {
    "targetCountry": "{TARGET_COUNTRY}",
    "contentLanguage": "{CONTENT_LANGUAGE}"
  },
  "input": "API"
}

Créer des promotions

Vous pouvez utiliser la méthode accounts.promotions.insert pour créer ou modifier une promotion. La méthode accounts.promotions.insert accepte une ressource promotions et un nom de source de données en entrée. Elle renvoie la promotion (nouvelle ou modifiée) si elle aboutit.

Pour créer une promotion, vous devez indiquer le nom de la source de données. Vous devez également indiquer les valeurs des champs suivants dans votre requête:

  • contentLanguage
  • redemptionChannel
  • promotionId
  • targetCountry
  • attributes.offerType
  • attributes.genericRedemptionCode
  • attributes.couponValueType
  • attributes.productApplicability
  • attributes.promotionEffectiveTimePeriod.endTime
  • attributes.promotionEffectiveTimePeriod.startTime
  • attributes.longTitle

Google examine et approuve vos promotions avant de les diffuser. Pour en savoir plus, consultez le processus d'approbation des promotions.

Nous vous recommandons de consulter le Règlement sur les promotions pour vous assurer que les promotions que vous créez ajoutent de la valeur et respectent le règlement des annonces Shopping.

La requête suivante montre comment créer une promotion en ligne:

POST https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions:insert

{
  "promotion": {
    "name": "{PROMOTION_NAME}",
    "promotionId": "{PROMOTION_ID}",
    "targetCountry": "{TARGET_COUNTRY}",
    "redemptionChannel": [
      "ONLINE"
    ],
    "contentLanguage": "{CONTENT_LANGUAGE}",
    "attributes": {
      "promotionDisplayTimePeriod": {
        "endTime": "{PROMOTION_END_TIME}",
        "startTime": "{PROMOTION_START_TIME}"
      },
      "offerType": "{OFFER_TYPE}",
      "longTitle": "{LONG_TITLE}"
    }
  },
  "dataSource": "accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}"
}

Pour en savoir plus sur les règles applicables à la définition de votre identifiant promotion, consultez la section Conditions minimales requises pour l'attribut identifiant promotion.

Les valeurs valides pour le champ offerType obligatoire sont NO_CODE et GENERIC_CODE. Si vous ne fournissez pas l'une de ces valeurs, la requête API échoue avec la réponse HTTP 400 [offer_type] validation/missing_required: Invalid or missing required attribute: offer_type. Un message d'erreur similaire s'affiche si vous ne fournissez aucun des champs obligatoires.

Si vous ne fournissez pas de valeur pour le champ attributes.genericRedemptionCode, la requête échoue avec la réponse HTTP 400 [genericRedemptionCode] No redemption code provided.

Les valeurs des champs promotion.attributes.promotionDisplayTimePeriod.startTime et promotion.attributes.promotionDisplayTimePeriod.endTime doivent être au format yyyy-mm-ddThh:mm:ssZ. Veillez à remplacer les valeurs de ces champs par des dates ultérieures.

Pour en savoir plus, consultez la spécification des données sur les promotions.

Pour connaître les bonnes pratiques à suivre pour créer une promotion, consultez la section Bonnes pratiques concernant les promotions.

Pour obtenir la liste des attributs liés aux promotions, consultez Ajouter des attributs pour les données structurées.

Une fois la requête de création de promotion exécutée, il peut s'écouler quelques minutes avant que la promotion puisse être récupérée à l'aide de l'API ou qu'elle apparaisse dans Merchant Center.

Voici un exemple que vous pouvez utiliser pour insérer plusieurs promotions de manière asynchrone:

Java
import com.google.api.core.ApiFuture;
import com.google.api.core.ApiFutureCallback;
import com.google.api.core.ApiFutures;
import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.common.util.concurrent.MoreExecutors;
import com.google.protobuf.Timestamp;
import com.google.shopping.merchant.promotions.v1beta.Attributes;
import com.google.shopping.merchant.promotions.v1beta.CouponValueType;
import com.google.shopping.merchant.promotions.v1beta.InsertPromotionRequest;
import com.google.shopping.merchant.promotions.v1beta.OfferType;
import com.google.shopping.merchant.promotions.v1beta.ProductApplicability;
import com.google.shopping.merchant.promotions.v1beta.Promotion;
import com.google.shopping.merchant.promotions.v1beta.PromotionsServiceClient;
import com.google.shopping.merchant.promotions.v1beta.PromotionsServiceSettings;
import com.google.shopping.merchant.promotions.v1beta.RedemptionChannel;
import com.google.shopping.type.CustomAttribute;
import com.google.shopping.type.Destination.DestinationEnum;
import com.google.type.Interval;
import java.util.ArrayList;
import java.util.List;
import java.util.Random;
import java.util.stream.Collectors;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;

/** This class demonstrates how to insert multiple promotions asynchronously. */
public class InsertPromotionsAsyncSample {

  private static String generateRandomString() {
    String characters = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
    Random random = new Random();
    StringBuilder sb = new StringBuilder(8);
    for (int i = 0; i < 8; i++) {
      sb.append(characters.charAt(random.nextInt(characters.length())));
    }
    return sb.toString();
  }

  private static Promotion createPromotion(String accountId) {
    String merchantPromotionId = generateRandomString();

    Attributes attributes =
        Attributes.newBuilder()
            .setProductApplicability(ProductApplicability.ALL_PRODUCTS)
            .setOfferType(OfferType.GENERIC_CODE)
            .setGenericRedemptionCode("ABCD1234")
            .setLongTitle("My promotion")
            .setCouponValueType(CouponValueType.PERCENT_OFF)
            .addPromotionDestinations(DestinationEnum.SHOPPING_ADS)
            .setPercentOff(10)
            // Note that promotions have a 6-month limit.
            // For more information, read here: https://support.google.com/merchants/answer/2906014
            // Also note that only promotions valid within the past 365 days are shown in the UI.
            .setPromotionEffectiveTimePeriod(
                Interval.newBuilder()
                    .setStartTime(Timestamp.newBuilder().setSeconds(1726842472))
                    .setEndTime(Timestamp.newBuilder().setSeconds(1726842473))
                    .build())
            .build();

    return Promotion.newBuilder()
        .setName(String.format("accounts/%s/merchantPromotions/%s", accountId, merchantPromotionId))
        .setPromotionId(merchantPromotionId)
        .setContentLanguage("fr")
        .setTargetCountry("CH")
        .addRedemptionChannel(RedemptionChannel.ONLINE)
        .setAttributes(attributes)
        // Custom attributes allow you to add additional information which is not available in
        // Attributes. For example, you might want to pilot experimental functionality.
        .addCustomAttributes(
            CustomAttribute.newBuilder()
                .setName("another example name")
                .setValue("another example value")
                .build())
        .build();
  }

  public static void asyncInsertPromotions(String accountId, String dataSourceId) throws Exception {
    GoogleCredentials credential = new Authenticator().authenticate();

    PromotionsServiceSettings merchantPromotionsServiceSettings =
        PromotionsServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    try (PromotionsServiceClient merchantPromotionsServiceClient =
        PromotionsServiceClient.create(merchantPromotionsServiceSettings)) {

      // Arbitrarily creates five merchant promotions with random IDs.
      List<InsertPromotionRequest> requests = new ArrayList<>();
      for (int i = 0; i < 5; i++) {
        InsertPromotionRequest request =
            InsertPromotionRequest.newBuilder()
                .setParent(String.format("accounts/%s", accountId))
                .setPromotion(createPromotion(accountId))
                .setDataSource(String.format("accounts/%s/dataSources/%s", accountId, dataSourceId))
                .build();
        requests.add(request);
      }

      // Inserts the merchant promotions.
      List<ApiFuture<Promotion>> futures =
          requests.stream()
              .map(
                  request ->
                      merchantPromotionsServiceClient.insertPromotionCallable().futureCall(request))
              .collect(Collectors.toList());

      // Creates callback to handle the responses when all are ready.
      ApiFuture<List<Promotion>> responses = ApiFutures.allAsList(futures);
      ApiFutures.addCallback(
          responses,
          new ApiFutureCallback<List<Promotion>>() {
            @Override
            public void onSuccess(List<Promotion> results) {
              System.out.println("Inserted merchant promotions below:");
              System.out.println(results);
            }

            @Override
            public void onFailure(Throwable throwable) {
              System.out.println(throwable);
            }
          },
          MoreExecutors.directExecutor());
    } catch (Exception e) {
      System.out.println(e);
    }
  }


  public static void main(String[] args) throws Exception {
    Config config = Config.load();
    asyncInsertPromotions(config.getAccountId().toString(), "<YOUR_DATA_SOURCE_ID>");
  }
}
InsertPromotionsAsyncSample.java

Voici quelques exemples de promotions que vous pouvez utiliser pour vous lancer.

Une promotion locale applicable à tous les produits et à tous les magasins

L'exemple de requête suivant montre comment créer une promotion locale applicable à tous les produits de votre compte Merchant Center et à tous les magasins ajoutés dans votre compte Fiche d'établissement associé.

POST https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions:insert

{
  "promotion": {
    "promotionId": "buy_2_get_10_off",
    "contentLanguage": "en",
    "targetCountry": "US",
    "redemptionChannel": [
      "IN_STORE"
    ],
    "attributes": {
      "longTitle": "Buy 2 and get 10$ OFF purchase",
      "productApplicability": "ALL_PRODUCTS",
      "offerType": "NO_CODE",
      "couponValueType": "BUY_M_GET_MONEY_OFF",
      "promotionDisplayTimePeriod": {
        "startTime": "2024-2-06T00:47:44Z",
        "endTime": "2024-5-06T00:47:44Z"
      },
      "promotionEffectiveTimePeriod": {
        "startTime": "2024-2-06T00:47:44Z",
        "endTime": "2024-5-06T00:47:44Z"
      },
      "moneyOffAmount": {
        "amountMicros": "1000000",
        "currencyCode": "USD"
      },
      "minimumPurchaseQuantity": 2,
      "storeApplicability": "ALL_STORES",
      "promotionUrl": "http://promotionnew4url.com/",
      "promotionDestinations": [
        "LOCAL_INVENTORY_ADS"
      ],
    }
  },
  "dataSource": "accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}"
}

Le champ productApplicability est obligatoire. Il indique si la promotion s'applique à tous les produits ou à certains seulement. Les valeurs acceptées sont ALL_PRODUCTS et SPECIFIC_PRODUCTS. Pour en savoir plus, consultez Choisir des produits pour votre promotion.

Le champ couponValueType est obligatoire. Il indique le type de promotion que vous diffusez. Pour obtenir la liste des valeurs acceptées, consultez la section Type de valeur du bon de réduction. Selon le type de valeur de bon de réduction que vous avez sélectionné, certains attributs sont obligatoires.

Le champ minimumPurchaseQuantity vous permet de définir la valeur de la quantité minimale d'articles à acheter pour pouvoir profiter de l'offre promotionnelle. Pour en savoir plus, consultez la section Nombre minimum d'articles à acheter pour la promotion.

De même, vous pouvez utiliser le champ minimumPurchaseAmount pour définir le montant minimal d'achat requis pour pouvoir profiter de la promotion. Pour en savoir plus, consultez la section Montant minimal de l'achat.

Pour en savoir plus sur les valeurs que vous devez fournir pour créer une promotion locale, consultez la section Spécifications de la source de données pour les promotions locales.

Une promotion en ligne s'appliquant à certains produits avec un code promotionnel

L'exemple de requête suivant montre comment créer une promotion en ligne qui s'applique à certains produits avec un code promotionnel.

POST https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions:insert

{
 "promotion": {
   "promotionId": "25_pct_off",
   "contentLanguage": "en",
   "targetCountry": "US",
   "redemptionChannel": [
     "ONLINE"
   ],
   "attributes": {
     "longTitle": "10% off on selected items",
     "productApplicability": "SPECIFIC_PRODUCTS",
     "offerType": "GENERIC_CODE",
     "genericRedemptionCode": "SPRINGSALE",
     "couponValueType": "PERCENT_OFF",
     "promotionDisplayTimePeriod": {
       "startTime": "2024-2-06T00:47:44Z",
       "endTime": "2024-5-06T00:47:44Z"
     },
     "promotionEffectiveTimePeriod": {
       "startTime": "2024-2-06T00:47:44Z",
       "endTime": "2024-5-06T00:47:44Z"
     },
     "percentOff": 25,
     "promotionDestinations": [
       "FREE_LISTINGS"
     ],
     "itemIdInclusion": [
       "1499860100",
       "1499860101",
       "1499860102",
       "1499860103",
       "1499860104"
     ],
   }
 },
 "dataSource": "accounts/{ACCOUNT_ID}/dataSources/1000000573361824"
}

Afficher les promotions

Pour afficher une promotion, utilisez accounts.promotions.get. Cette requête GET est en lecture seule. Il nécessite votre merchantId et l'identifiant de la promotion. La méthode GET renvoie la ressource de promotions correspondante.

Exemple :

GET https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions/{PROMOTION_ID}

Remplacez les éléments suivants :

  • {ACCOUNT_ID}: identifiant unique de votre compte Merchant Center.
  • {PROMOTION_ID}: identifiant unique de la promotion que vous souhaitez récupérer. Le format est {CHANNEL}~{CONTENT_LANGUAGE}~{TARGET_COUNTRY}~{PROMOTION_ID}.

Notez qu'il faut quelques minutes pour qu'une promotion nouvellement créée puisse être récupérée à l'aide de l'API.

Afficher une promotion locale

L'exemple de requête suivant permet de récupérer une promotion en magasin dont l'ID est in_store~en~US~buy_2_get_10_off.

GET https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions/in_store~en~US~buy_2_get_10_off

Une fois la requête effectuée, la réponse suivante s'affiche:

{
 "name": "accounts/{ACCOUNT_ID}/promotions/in_store~en~US~buy_2_get_10_off",
 "promotionId": "buy_2_get_10_off",
 "contentLanguage": "en",
 "targetCountry": "US",
 "redemptionChannel": [
   "IN_STORE"
 ],
 "attributes": {
   "longTitle": "Buy 2 and get 10$ OFF purchase",
   "productApplicability": "ALL_PRODUCTS",
   "offerType": "NO_CODE",
   "couponValueType": "BUY_M_GET_MONEY_OFF",
   "promotionDisplayTimePeriod": {
     "startTime": "2024-2-06T00:47:44Z",
     "endTime": "2024-5-06T00:47:44Z"
   },
   "promotionEffectiveTimePeriod": {
     "startTime": "2024-2-06T00:47:44Z",
     "endTime": "2024-5-06T00:47:44Z"
   },
   "moneyOffAmount": {
     "amountMicros": "1000000",
     "currencyCode": "USD"
   },
   "minimumPurchaseQuantity": 2,
   "storeApplicability": "ALL_STORES",
   "promotionUrl": "http://promotionnew4url.com/",
   "promotionDestinations": [
     "LOCAL_INVENTORY_ADS"
   ],
 }
 "dataSource": "accounts/{ACCOUNT_ID}/dataSources/1000000573361824"
}

Le champ moneyOffAmount de cet exemple indique la remise proposée dans la promotion. Pour en savoir plus, consultez la section Montant de la remise financière d'une promotion.

Le champ promotionUrl de cet exemple fournit le lien vers le site Web du magasin, où les clients peuvent trouver plus d'informations sur la promotion. Les promotions des annonces produits en magasin renvoient une erreur si vous n'incluez pas le champ promotionUrl.

Afficher une promotion en ligne

L'exemple de requête suivant permet de récupérer une promotion en ligne dont l'ID est online~en~US~25_pct_off.

GET https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions/online~en~US~25_pct_off
{
 "name": "accounts/{ACCOUNT_ID}/promotions/online~en~US~25_pct_off",
 "promotionId": "25_pct_off",
 "contentLanguage": "en",
 "targetCountry": "US",
 "redemptionChannel": [
   "ONLINE"
 ],
 "attributes": {
   "longTitle": "10% off on selected items",
   "productApplicability": "SPECIFIC_PRODUCTS",
   "offerType": "GENERIC_CODE",
   "genericRedemptionCode": "WINTERGIFT",
   "couponValueType": "PERCENT_OFF",
   "promotionDisplayTimePeriod": {
     "startTime": "2024-2-06T00:47:44Z",
     "endTime": "2024-5-06T00:47:44Z"
   },
   "promotionEffectiveTimePeriod": {
     "startTime": "2024-2-06T00:47:44Z",
     "endTime": "2024-5-06T00:47:44Z"
   },
   "percentOff": 25,
   "promotionDestinations": [
     "FREE_LISTINGS"
   ],
   "itemIdInclusion": [
     "1499860100",
     "1499860101",
     "1499860102",
     "1499860103",
     "1499860104"
   ],
 }
 "dataSource": "accounts/{ACCOUNT_ID}/dataSources/{dataSource}"
}

Le champ itemIdInclusion utilisé dans cet exemple mentionne les produits éligibles à la promotion. Pour en savoir plus, consultez ID produit pour la promotion.

Lister les promotions

Vous pouvez utiliser la méthode promotions.list pour afficher toutes les promotions créées.

GET https://merchantapi.googleapis.com/promotions/v1beta/{ACCOUNT_ID}/promotions

La réponse contient la liste de toutes les promotions de votre compte. Pour chaque promotion, vous pouvez consulter des informations telles que promotionId, redemptionChannel, dataSource, promotionStatus et plus encore.

Afficher l'état d'une promotion

Pour connaître l'état d'une promotion, consultez l'attribut promotionStatus renvoyé par la méthode promotions.get ou promotions.list.

Le champ promotionStatus peut présenter les valeurs suivantes:

  • IN_REVIEW: la promotion est toujours en cours d'examen.
  • REJECTED: la promotion est refusée.
  • LIVE: la promotion est approuvée et active.
  • STOPPED: la promotion est arrêtée par le compte.
  • EXPIRED: la promotion n'est plus active.
  • PENDING: la promotion n'est pas arrêtée et toutes les évaluations sont approuvées, mais la date d'activation est à venir.
  • STATE_UNSPECIFIED: état de la promotion inconnu.

Pour comprendre le processus d'approbation d'une promotion que vous avez créée, consultez la section Processus d'approbation des promotions.

Exemples d'états de promotion

Les exemples suivants montrent la différence entre les requêtes réussies et celles qui échouent.

Mise en correspondance des produits manquante

Le corps de réponse suivant montre une promotion en ligne refusée en raison d'un mappage de produits manquant.

  "promotionStatus": {
    "destinationStatuses": [
      {
        "reportingContext": "FREE_LISTINGS",
        "status": "REJECTED"
      }
    ],
    "itemLevelIssues": [
      {
        "code": "promotion_sku_unmapped",
        "severity": "DISAPPROVED",
        "resolution": "merchant_action",
        "reportingContext": "FREE_LISTINGS",
        "description": "Unmapped",
        "detail": "This promotion couldn't be tested during review because it doesn't apply to any products that are currently in your Products feed",
        "documentation": "https://support.google.com/merchants/answer/2906014",
        "applicableCountries": [
          "US"
        ]
      },
      {
        "code": "promotion_sku_additional_requirements",
        "severity": "DISAPPROVED",
        "resolution": "merchant_action",
        "reportingContext": "FREE_LISTINGS",
        "description": "Promotion conditions not allowed",
        "detail": "This promotion has additional requirements that are not allowed such as requiring customers to verify additional details like phone number or ID before showing the promotion details",
        "documentation": "https://support.google.com/merchants/answer/2906014",
        "applicableCountries": [
          "US"
        ]
      }
    ]
  }

Pour résoudre les problèmes liés aux promotions refusées et découvrir comment éviter les refus à l'avenir, consultez Résoudre les problèmes liés aux promotions refusées.

Si une promotion que vous avez créée n'est pas approuvée, vous recevez un e-mail indiquant le motif du refus et des instructions pour résoudre les problèmes.

Promotion en cours d'évaluation

Le corps de réponse suivant affiche une promotion qui est toujours en cours d'évaluation.

  "promotionStatus": {
    "destinationStatuses": [
      {
        "reportingContext": "FREE_LISTINGS",
        "status": "PENDING"
      },
      {
        "destination": "SHOPPING_ADS",
        "status": "PENDING"
      }
    ],
    "itemLevelIssues": []
  }

Une promotion approuvée et en cours

Le corps de réponse suivant affiche une promotion visible par les acheteurs.

  "promotionStatus": {
    "destinationStatuses": [
      {
        "reportingContext": "FREE_LISTINGS",
        "status": "LIVE"
      },
      {
        "destination": "SHOPPING_ADS",
        "status": "LIVE"
 }  ],
    "itemLevelIssues": []
  }

Pour en savoir plus, consultez les questions fréquentes sur l'état des promotions.

En savoir plus