Google Ads API : versions, dates de sunset et méthode de migration

Chaque version de la Google Ads API a une date d'arrêt (« sunset ») : passé cette date, tous les appels vers cette version échouent, alors que vos campagnes continuent de tourner normalement dans Google Ads. Google vise un arrêt environ un an après la sortie d'une version, publie une nouvelle version tous les 3 à 4 mois en moyenne et limite à deux le nombre de mises à niveau à faire par an¹. Au 7 octobre 2026, la version la plus urgente à quitter est la v22, dont l'arrêt est prévu en octobre 2026.

Pour un dirigeant, l'enjeu est concret : un rapport automatique, un import de ventes ou un outil maison qui appelle une version arrêtée cesse simplement de fonctionner, sans que rien ne change dans vos campagnes. Si ces outils ont été développés par un prestataire qui ne les maintient plus, c'est à vérifier avant la date d'arrêt, pas après.

Quelles versions sont disponibles et jusqu'à quand ?

Source : calendrier officiel, page mise à jour par Google le 30 septembre 2026 et relevée le 7 octobre 2026¹. Une date « indicative » (tentative) signifie que l'arrêt peut intervenir à n'importe quel moment du mois annoncé, et que la date peut encore bouger. La v26.1 est désignée comme une version facultative à cause du chevauchement avec la période des fêtes. Consultez la page officielle avant de planifier.

Les règles annoncées par Google : au plus cinq versions majeures disponibles en même temps, une durée de vie d'environ 12 mois pour une version majeure et 10 mois pour une version mineure, au plus deux mises à niveau par an, et la possibilité de passer directement de la version N à la version N+2¹. Google annonce aussi au moins 20 semaines entre la sortie des bibliothèques clientes de la dernière version et la date d'arrêt de la version retirée¹.

Quelle différence entre version dépréciée et version arrêtée ?

• Dépréciée : toute version qui n'est plus la plus récente. Elle fonctionne normalement, reste supportée, mais ne reçoit plus de nouvelles fonctionnalités¹.
• Arrêtée (sunset) : les appels échouent à partir de la date d'arrêt. Il faut migrer immédiatement¹.

Les versions « mineures » (v24.1, v25.2…) n'introduisent pas de changement bloquant ; seules les versions majeures (v24, v25, v26) en contiennent².

Comment savoir quelles versions votre projet appelle encore ?

Dans la Google Cloud Console, ouvrez API et services, cliquez sur Google Ads API, puis sur l'onglet Metrics. Le tableau des méthodes affiche des noms comme google.ads.googleads.v25.services.GoogleAdsService.Mutate : le numéro de version y figure¹. C'est le moyen le plus sûr de repérer un vieux script oublié sur un serveur.

Comment préparer une migration ?

1. Choisir la version cible

Il n'est pas obligatoire de passer par chaque version : on peut monter de la version N à la version N+2 directement¹. Viser la plus récente donne le plus de marge avant le prochain arrêt : si votre code tourne encore en v22 (arrêt en octobre 2026, date indicative) ou en v23 (février 2027), la v25 évite une deuxième migration à court terme. En revanche, lisez les notes de chaque version majeure intermédiaire et ses guides de mise à niveau, car les changements bloquants s'additionnent². Les deux sections suivantes résument ceux de la v24 et de la v25.

2. Inventorier ce que votre code utilise

• les services et méthodes appelés ;
• les champs, ressources et valeurs d'énumération présents dans vos requêtes GAQL et vos modifications ;
• la version de la bibliothèque cliente installée.

Recherchez ensuite dans votre code chaque champ supprimé ou renommé listé dans les notes de version, par exemple ceux des tableaux ci-dessous.

3. Mettre à jour la bibliothèque cliente

Chaque version de l'API exige une version minimale de la bibliothèque officielle¹ :

Google ne publie pas de bibliothèque officielle en Go : les langages absents du tableau passent par l'interface REST. Ces minimums valent pour la version majeure ; pour une version mineure, consultez le ChangeLog de la bibliothèque. Attention au sens inverse : les nouvelles versions des bibliothèques retirent les versions d'API dépréciées. La bibliothèque Python 33.0.0, par exemple, ne contient plus que v23, v24 et v25, et demande Python 3.9 ou plus récent³. Mettre à jour la bibliothèque sans toucher au code peut donc casser un appel qui force une ancienne version. En Python, fixez la version explicitement :

from google.ads.googleads.client import GoogleAdsClient

# Fixer explicitement la version évite de changer d'API sans le savoir
# lors d'une mise à jour de la bibliothèque.
client = GoogleAdsClient.load_from_storage("google-ads.yaml", version="v25")
ga_service = client.get_service("GoogleAdsService")

4. Tester sur un compte de test

Créez un compte de test sous un compte administrateur de test (50 comptes de test maximum par hiérarchie⁴) et rejouez vos requêtes GAQL et vos modifications, en particulier celles touchées par les changements bloquants.

5. Déployer progressivement

Commencez par un ou deux comptes peu critiques, surveillez les erreurs, puis étendez. Gardez la possibilité de revenir à l'ancienne version tant qu'elle n'est pas arrêtée : c'est l'avantage de fixer la version dans le code.

Quels changements bloquants la v24 a-t-elle introduits ?

La v24 est sortie le 22 avril 2026 et doit être arrêtée en mai 2027¹. Ce n'est plus la version la plus récente, mais elle intéresse ceux qui migrent depuis la v23 ou une version antérieure. Liste d'après les notes de version officielles² :

Un champ supprimé ne sera pas ignoré silencieusement : une requête qui le référence échoue, ce qui est plutôt une bonne nouvelle pour repérer les oublis en test. Exemple de création d'annonce Demand Gen vidéo conforme à la v24, avec la bibliothèque Python officielle :

# Bibliothèque google-ads >= 30.1.0, client initialisé en version "v24" ou plus récente
ad = client.get_type("Ad")
info = ad.demand_gen_video_responsive_ad

headline = client.get_type("AdTextAsset")
headline.text = "Votre titre"
info.headlines.append(headline)

description = client.get_type("AdTextAsset")
description.text = "Votre description"
info.descriptions.append(description)

# Obligatoires depuis la v24 : sans eux, la création échoue
video = client.get_type("AdVideoAsset")
video.asset = video_asset_resource_name
info.videos.append(video)

logo = client.get_type("AdImageAsset")
logo.asset = logo_asset_resource_name
info.logo_images.append(logo)

Dans cet exemple, video_asset_resource_name et logo_asset_resource_name sont les noms de ressource d'éléments vidéo et logo déjà créés dans le compte.

Quelles nouveautés la v24 apporte-t-elle ?

• Rapports Shopping : CartDataSalesView. Nouvelle ressource qui segmente les conversions par produit réellement vendu, et non plus seulement par produit cliqué. S'y ajoutent des métriques « non enchérissables » (all_revenue_micros, all_gross_profit_micros, all_units_sold…) et le segment conversion_attribution_event_type dans ShoppingPerformanceView².
• Conversions de prospects GA4 et Firebase. Neuf nouvelles valeurs de ConversionActionType pour les étapes « générer », « qualifier » et « conclure » un prospect, côté Google Analytics 4 et Firebase (Android, iOS)². Elles concernent les conversions importées de GA4 ou Firebase, pas l'import de conversions hors ligne.
• Optimisation des conversions après affichage. Nouveau champ Campaign.view_through_conversion_optimization_enabled (faux par défaut) pour les campagnes Demand Gen et pour applications².
• Exclusions de genre dans Performance Max. Via CampaignCriterion.gender ; Google précise que la fonction est ouverte sur toutes les versions de l'API, pas seulement la v24².
• Filtrage de produits par étiquettes avec des expressions logiques (RETAIL_FILTER_BUNDLE, RETAIL_FILTER) pour les campagnes Shopping, réservé aux comptes sur liste d'autorisation².
• Divers : lecture des données de flux voyage (AssetSet.travel_feed_data), campagnes pour applications dans ShoppingProduct, nouvelle erreur UserListErrorEnum.DUPLICATE_LOOKALIKE².

Pour le pilotage de Performance Max par l'API, voir notre tutoriel Google Ads API avec Python, qui contient un cas d'usage complet.

Quels changements bloquants la v25 a-t-elle introduits ?

La v25, sortie le 22 juillet 2026, est la version majeure actuelle. Principaux changements bloquants d'après les notes de version² :

Quels changements ne dépendent pas d'un numéro de version ?

Google publie aussi des changements qui s'appliquent à toutes les versions en même temps, suivis sur une page dédiée⁵. En 2026 :

• 9 septembre 2026 : fin des developer tokens ; les niveaux d'accès sont portés par le projet Google Cloud⁶.
• 23 septembre 2026 : plus de création de nouvelles campagnes intelligentes ; les existantes continuent de diffuser et restent modifiables⁵.
• Septembre 2026 : le ciblage linguistique manuel (CampaignCriterion.language) n'est plus pris en charge sur les campagnes Search ; l'ajouter échoue avec ContextError.OPERATION_NOT_PERMITTED_FOR_CONTEXT⁵.
• 15 juin 2026 : l'import de conversions hors ligne via l'API est réservé aux intégrations existantes ; les nouvelles passent par la Data Manager API (voir notre guide de l'import de conversions hors ligne par API)⁵.
• 1er juin 2026 : les données de rapport détaillées (jour, heure, semaine) ne sont plus disponibles au-delà de 37 mois ; les données mensuelles, trimestrielles et annuelles restent disponibles 11 ans⁵.
• 1er avril 2026 : budget quotidien minimum de 5 USD (ou équivalent) pour toutes les campagnes Demand Gen, sous peine d'erreur BUDGET_BELOW_DAILY_MINIMUM ; restriction d'accès à l'API pour les workflows Customer Match des tokens sans activité de ce type sur la période de référence⁵.
• 2 février 2026 : les nouveaux utilisateurs des attributs de session ou des adresses IP dans les imports de conversions sont restreints, au profit de la Data Manager API⁵.
• Janvier 2026 : plus de création de nouvelles annonces « appel uniquement » ; les existantes cesseront de diffuser en février 2027 et leur prise en charge par l'API sera supprimée⁵.

Comment ne plus être surpris par un arrêt ?

• Abonnez-vous au blog des développeurs Google Ads, où Google publie les rappels d'arrêt¹.
• Vérifiez que les développeurs concernés ont un rôle de propriétaire ou d'éditeur sur le projet Google Cloud : Google y envoie désormais les annonces de service obligatoires⁶.
• Ajoutez la date d'arrêt de votre version au calendrier de l'équipe, avec une alerte plusieurs semaines avant.
• Planifiez une mise à niveau au moins une fois par an, idéalement deux, au rythme recommandé par Google.

Si vos outils Google Ads ont été développés par un prestataire qui ne les maintient plus, notre équipe de gestion de comptes Google Ads peut faire le point lors d'un audit gratuit.