Shopify Global Catalog : migrer de REST vers MCP/UCP avant le 2 novembre

Le 2 novembre 2026, Shopify coupera le trafic de son Global Catalog REST API. Déprécié depuis avril, ce service de découverte de produits multi-marchands ne répondra plus sur ses anciens endpoints /global/.... Annoncée le 9 octobre 2026, l'échéance impose de migrer les intégrations concernées vers Global Catalog MCP, qui suit le Universal Commerce Protocol (UCP).

Ce changement ne signifie pas que Shopify supprime toutes ses API REST : il vise précisément Global Catalog, utilisé pour chercher des produits parmi plusieurs boutiques Shopify. Pour un développeur d'intégration e-commerce, de SaaS ou d'agent d'achat, la migration exige davantage qu'un remplacement d'URL : il faut adapter le transport, les outils appelés, les identifiants, le profil de l'agent et les schémas des réponses. Voici quatre conversions REST → MCP, puis une méthode de validation avant l'arrêt.

Quelles intégrations Shopify cessent de fonctionner le 2 novembre ?

Seuls les clients de l'ancien Global Catalog REST API sont visés. Il s'agit du service qui permettait de découvrir et consulter des produits au-delà d'une seule boutique, sur le domaine discover.shopifyapps.com. Shopify annonce l'arrêt de tous les chemins /global/... correspondants, y compris les endpoints de catalogues sauvegardés.

Ce n'est ni l'arrêt de l'Admin API, ni celui de la Storefront API, ni une migration obligatoire de toutes les boutiques vers MCP. Pour un agent limité au catalogue d'un seul marchand, Shopify distingue d'ailleurs Storefront Catalog MCP de Global Catalog MCP. Commencez donc par inventorier les domaines et routes utilisés par votre application : ne modifiez pas des intégrations non concernées.

Le mapping officiel : quatre endpoints REST vers trois outils MCP

Ce mapping a été publié par Shopify le 9 octobre. Dans MCP, on n'appelle pas quatre chemins HTTP distincts : on envoie une requête JSON-RPC tools/call à un point d'entrée commun, puis le nom de l'outil apparaît dans params.name. Les arguments métier sont regroupés dans params.arguments.catalog.

Préparer le client : endpoint MCP, profil UCP et authentification

L'endpoint de destination est https://catalog.shopify.com/api/ucp/mcp. Chaque appel doit contenir params.arguments.meta.ucp-agent.profile, soit l'URL du profil UCP de votre agent. Ce profil indique les capacités que l'agent revendique ; le serveur négocie les outils et champs disponibles. Les exemples suivants utilisent le profil d'illustration hébergé par Shopify, à remplacer par le profil de votre application en production.

Pour exposer les outils globaux et leurs champs enrichis, Shopify précise qu'un profil personnalisé doit déclarer les capacités de base dev.ucp.shopping.catalog.search et dev.ucp.shopping.catalog.lookup, ainsi que l'extension dev.shopify.catalog.global. Une extension isolée de sa capacité de base ne suffit pas.

L'authentification bearer existante peut être conservée : les jetons créés à partir des identifiants client du Dev Dashboard restent utilisables. En revanche, le corps de la requête n'est plus un JSON propre à l'ancien endpoint REST. Le code ci-dessous illustre le transport HTTP vers MCP ; la configuration réelle dépend du client et de la gestion de session MCP utilisés.

# Enregistrer le premier JSON dans 01-search-catalog.json
# Utiliser un jeton personnel/serveur obtenu via le Dev Dashboard.
curl -X POST 'https://catalog.shopify.com/api/ucp/mcp' \
  -H 'Authorization: Bearer <SHOPIFY_CATALOG_TOKEN>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data-binary @01-search-catalog.json

Attention : le fichier 01-search-catalog.json doit contenir l'enveloppe complète présentée dans l'exemple suivant. Ne placez jamais un jeton réel dans un fichier public, un navigateur ou un dépôt de démonstration ; utilisez les secrets de votre backend.

Tutoriel : migrer quatre requêtes REST sans perdre leur logique

1. Recherche multi-marchands : GET /global/v2/search → search_catalog

Avant : le backend interrogeait GET https://discover.shopifyapps.com/global/v2/search, avec ses paramètres REST de recherche. Après : il appelle search_catalog avec une requête texte dans catalog.query, le pays de l'acheteur dans catalog.context.address_country et la limite dans catalog.pagination.limit.

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 1,
  "params": {
    "name": "search_catalog",
    "arguments": {
      "meta": {
        "ucp-agent": {
          "profile": "https://shopify.dev/ucp/agent-profiles/examples/2026-08-25/valid-with-capabilities.json"
        }
      },
      "catalog": {
        "query": "chaussures de course",
        "context": {
          "address_country": "FR",
          "language": "fr"
        },
        "pagination": {
          "limit": 10
        }
      }
    }
  }
}

La réponse UCP regroupe les produits et leurs offres issues de plusieurs marchands. Selon la recherche, les filtres, informations de disponibilité et données enrichies peuvent modifier le résultat : vérifiez votre affichage métier, plutôt que de supposer que le schéma REST reste inchangé.

2. Fiche produit : GET /global/v2/p/{upid} → get_product

Avant : une fiche était lue via GET https://discover.shopifyapps.com/global/v2/p/{upid}. Après : l'outil get_product prend un identifiant canonique au format gid://shopify/p/{upid} dans catalog.id.

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 2,
  "params": {
    "name": "get_product",
    "arguments": {
      "meta": {
        "ucp-agent": {
          "profile": "https://shopify.dev/ucp/agent-profiles/examples/2026-08-25/valid-with-capabilities.json"
        }
      },
      "catalog": {
        "id": "gid://shopify/p/7f3a2b8c1d9e",
        "context": {
          "address_country": "FR"
        }
      }
    }
  }
}

L'outil peut retourner les options, les variantes et les signaux de disponibilité, puis aider à préciser la sélection. Remplacer le chemin REST par une chaîne GID au bon endroit est essentiel : transmettre simplement l'ancien identifiant brut dans le nouveau format risque de produire un résultat incorrect ou introuvable.

3. Variante : GET /global/v2/p/by-variant/{vid} → get_product

Avant : le lookup par variante utilisait GET https://discover.shopifyapps.com/global/v2/p/by-variant/{vid}. Après : on appelle le même outil get_product, mais avec gid://shopify/ProductVariant/{vid}. Cette distinction compte pour un assistant qui part d'une référence précise plutôt que d'une fiche produit globale.

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 3,
  "params": {
    "name": "get_product",
    "arguments": {
      "meta": {
        "ucp-agent": {
          "profile": "https://shopify.dev/ucp/agent-profiles/examples/2026-08-25/valid-with-capabilities.json"
        }
      },
      "catalog": {
        "id": "gid://shopify/ProductVariant/87654321",
        "context": {
          "address_country": "FR"
        }
      }
    }
  }
}

Lorsque l'agent doit sélectionner une couleur ou une taille, le tableau optionnel catalog.selected permet de transmettre des choix sous la forme {"name":"Color","label":"Black"}. Les réponses de get_product exposent les choix effectifs et les indicateurs available ou exists.

4. Lookup de lots : POST /global/v2/lookup → lookup_catalog

Avant : plusieurs références pouvaient être résolues via POST https://discover.shopifyapps.com/global/v2/lookup. Après : la liste est passée dans catalog.ids, contenant entre 1 et 50 identifiants par appel. Le service accepte des GID de produits, de variantes et des URL de produits Shopify prises en charge.

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 4,
  "params": {
    "name": "lookup_catalog",
    "arguments": {
      "meta": {
        "ucp-agent": {
          "profile": "https://shopify.dev/ucp/agent-profiles/examples/2026-08-25/valid-with-capabilities.json"
        }
      },
      "catalog": {
        "ids": [
          "gid://shopify/p/7f3a2b8c1d9e",
          "gid://shopify/ProductVariant/87654321"
        ],
        "context": {
          "address_country": "FR"
        }
      }
    }
  }
}

Prévoyez un découpage en paquets de 50 au maximum si votre application charge de grands lots. Shopify précise que les identifiants renvoyant vers le même produit peuvent être regroupés, et que les ID introuvables apparaissent notamment sous forme de messages not_found : ce n'est donc pas toujours une correspondance « une entrée, une ligne en sortie ».

Et si l'application utilise des catalogues enregistrés ?

Les anciennes URL REST dédiées aux catalogues sauvegardés cessent également de fonctionner. Avec UCP, il faut passer l'identifiant du catalogue configuré dans le Dev Dashboard via catalog.catalog_id, au sein du même objet catalog. Cet identifiant s'ajoute aux autres paramètres métier, comme query ; ce n'est plus un segment d'URL.

Dans un appel search_catalog, les filtres du catalogue sauvegardé délimitent la recherche. Shopify précise aussi qu'un préfixe de recherche enregistré peut être combiné avec catalog.query. L'ancien alias catalog.saved_catalog_slug est documenté comme déprécié : préférez catalog.catalog_id pour une nouvelle intégration.

Adapter les schémas UCP dans le code applicatif

La différence ne s'arrête pas à l'appel d'outil. Les exemples Shopify renvoient des contenus structurés dans result.structuredContent : les produits possèdent de nouveaux champs, une enveloppe ucp décrit les capacités et versions négociées, et la pagination peut contenir cursor et has_next_page. Les montants tels que price_range.min.amount sont exprimés en unités monétaires mineures : ne les affichez pas directement comme des euros ou des dollars.

Un adaptateur entre le client MCP et l'application réduit le risque de coupler tout le front-end au schéma de transport. Ce petit exemple JavaScript suppose qu'un client MCP a déjà décodé la réponse JSON-RPC et ne remplace pas la validation complète des données métier :

// Réponse JSON-RPC déjà décodée par le client MCP
function normalizeCatalogResponse(rpcResponse) {
  if (rpcResponse.error) {
    throw new Error(rpcResponse.error.message || "Erreur MCP");
  }

  const data = rpcResponse.result?.structuredContent;
  if (!data) {
    throw new Error("Réponse UCP structurée absente");
  }

  return {
    products: Array.isArray(data.products) ? data.products : [],
    messages: Array.isArray(data.messages) ? data.messages : [],
    pagination: data.pagination ?? null,
  };
}

// data.products[i].price_range.min.amount : montant en unités mineures
// data.messages peut inclure un code "not_found" pour un ID inconnu

Autre nuance importante pour un comparateur : Shopify marque certains attributs de catalogue comme Inferred (descriptions enrichies, options normalisées, caractéristiques déduites). Ils peuvent être incomplets ou approximatifs. Ne les présentez pas automatiquement comme des affirmations originales du marchand. Pour les prix, variantes, liens de checkout et disponibilité, vérifiez les schémas et règles métier avant mise en production.

Tester la migration avant la coupure

Shopify met à disposition l'AI Toolkit et la CLI UCP pour tester les outils sans commencer par intégrer tout un client maison. Les commandes suivantes reprennent la syntaxe documentée, avec des valeurs d'exemple et un pays d'acheteur français :

# Essai de recherche, selon les exemples de la CLI UCP Shopify
ucp catalog search \
  --set /query='chaussures de course' \
  --set /context/address_country=FR \
  --view :compact --format md

# Test de résolution d’une variante connue
ucp catalog lookup \
  --set '/ids/0=gid://shopify/ProductVariant/87654321'

Pour sécuriser la bascule, préparez un petit jeu d'essais comprenant une requête texte, une fiche produit existante, une variante existante, une variante inconnue, un lot de plus de 50 IDs à découper et une recherche ciblée sur un catalogue enregistré. Comparez les résultats au comportement métier attendu : champs manquants, regroupements, pagination, prix et localisation. Surveillez la fréquence des erreurs not_found, les délais et les restrictions des politiques UCP.

REST → MCP : un précédent intéressant, pas la fin des API classiques

La leçon dépasse Shopify. Pour un workflow où un agent choisit dynamiquement un outil afin de découvrir des produits, une interface MCP accompagnée de schémas UCP et d'une négociation de capacités peut simplifier l'interopérabilité entre fournisseurs et assistants. Le serveur expose des opérations métier nommées plutôt qu'une série d'URL spécialisées ; l'agent peut choisir search_catalog, puis get_product en fonction de son objectif.

Mais MCP n'est pas un remplacement systématique de REST. Les API web traditionnelles et les schémas GraphQL restent adaptés à d'autres applications : interfaces prévisibles, synchronisation de données, opérations administratives ou intégration boutique à boutique. Ici, Shopify modernise un cas précis de découverte multi-marchands orienté agents. Le vrai critère d'architecture est le besoin d'interopérabilité agent/outil, pas l'idée qu'un protocole serait intrinsèquement supérieur dans tous les scénarios.

Pour un SaaS ou un assistant e-commerce, la décision pratique est donc simple : migrer maintenant les appels Global Catalog REST, isoler la nouvelle dépendance derrière un adaptateur de données, conserver une suite de tests métier et ne généraliser MCP que là où la nature du workflow le justifie.