Le modèle de données HubSpot, vu par un intégrateur : ce qu'il faut décider avant de brancher

Une intégration HubSpot échoue rarement sur l'API. Elle échoue sur une question posée trop tard : où range-t-on la donnée, et à quoi la reconnaît-on ? Une commande devient-elle une transaction ? Une entreprise se retrouve-t-elle par son domaine ou par son SIREN ? Qui fait foi quand deux outils écrivent sur la même fiche ? Tant que ces réponses ne sont pas écrites, chaque scénario les tranche à sa façon, et la base se remplit de doublons qu'aucune règle ne rattrape.

Voici le modèle de données de HubSpot tel qu'un intégrateur le lit : les objets, les identifiants, les associations, et les limites qui changent l'architecture selon l'abonnement.

Fonctionnement et limites relevés dans la base de connaissances HubSpot, son catalogue des produits et sa documentation développeurs, le 8 octobre 2026.

Les objets : ce qui existe sans rien payer

Le CRM de HubSpot range tout dans des objets, chacun avec ses fiches et ses propriétés. Les objets standard sont disponibles sur tous les abonnements, gratuit compris :

• les contacts et les entreprises — les personnes et les organisations ;
• les transactions (deals) — une vente en cours, qui avance dans un pipeline ;
• les produits, les lignes de produit, les devis, les factures et les abonnements ;
• les commandes et les paniers — les objets « commerce », pensés pour les achats confirmés et les paniers d'une boutique en ligne.

Les objets personnalisés — un « contrat », un « équipement », un « site client » — demandent un abonnement Enterprise, quel que soit le hub, avec un plafond de dix définitions d'objet.

Les identifiants : comment HubSpot reconnaît une fiche

C'est la partie qui décide de la qualité de toute la base.

Un contact se reconnaît à son adresse e-mail. HubSpot dédoublonne automatiquement les contacts sur l'e-mail : un formulaire ou un import qui arrive avec une adresse connue met à jour la fiche existante au lieu d'en créer une seconde.

Une entreprise se reconnaît à son domaine. HubSpot dédoublonne les entreprises sur le nom de domaine principal — sauf quand elles sont créées par l'API. La base de connaissances l'écrit noir sur blanc : les entreprises créées par l'API ne sont pas dédoublonnées sur le domaine.

L'identifiant HubSpot de chaque fiche (Record ID) est la seule clé que HubSpot garantit. Pour tout le reste, il faut la poser soi-même. Les propriétés à valeur unique servent à ça : jusqu'à dix par objet, sur des champs texte, téléphone ou nombre, et réglées uniquement à la création de la propriété. On y range l'identifiant du client dans Shopify, le SIREN d'une entreprise, la référence d'un logiciel métier : HubSpot refuse alors qu'une seconde fiche porte la même valeur. Le SIREN est d'ailleurs la clé qui évite les clients en double quand HubSpot se relie à la comptabilité, comme avec l'intégration HubSpot ↔ Pennylane.

Les propriétés : le mur du gratuit

C'est la limite qui surprend le plus. D'après le catalogue des produits de HubSpot, les outils gratuits n'autorisent que dix propriétés personnalisées au total, tous objets confondus. Dès Starter, on passe à 1 000 par objet.

Dix propriétés, c'est vite consommé : un identifiant externe, un SIREN, un canal d'acquisition, un segment client, et déjà une intégration sérieuse demande davantage. Si le projet suppose de faire remonter de la donnée métier dans HubSpot, Starter est le vrai point de départ, pas le gratuit.

Les associations : relier sans dupliquer

Deux fiches se relient par une association : un contact à son entreprise, une transaction à ses contacts, un ticket à la commande qui l'a provoqué.

Deux règles à connaître :

• L'entreprise principale. La première entreprise associée à un contact devient son entreprise principale, et c'est à elle seule que remontent ses activités. Un contact qui change d'employeur, ou un consultant rattaché à plusieurs clients, doit être traité délibérément.
• Les libellés d'association (« décideur », « payeur », « filiale de ») décrivent la nature du lien. Ils demandent un abonnement Professional ou Enterprise, jusqu'à 50 libellés par paire d'objets.

Sans libellés, on contourne souvent par une propriété sur le contact (« rôle : décideur »). Ça marche tant que le contact n'a qu'une entreprise — c'est-à-dire jusqu'au premier groupe ou au premier cabinet.

Commande ou transaction : la décision qui structure tout

Pour une boutique en ligne, c'est la question centrale. L'intégration officielle HubSpot ↔ Shopify y répond pour vous : elle synchronise les contacts et les produits dans les deux sens, les entreprises seulement avec Shopify Plus, et fait remonter les commandes et les paniers abandonnés de Shopify vers HubSpot, où ils ne se modifient pas. Elle ne crée pas de transactions.

C'est le bon choix par défaut. En B2C, une commande payée n'est pas une négociation : en faire une transaction remplit le pipeline de ventes déjà gagnées et fausse tous les rapports commerciaux.

Il y a une exception, et je l'ai rencontrée : la vente à panier élevé, où le client pose des questions avant d'acheter. Là, la vente a un vrai cycle, et la transaction suit ce cycle du premier échange jusqu'à la commande. C'est le schéma de cette synchronisation Shopify ↔ CRM, où la livraison et le SAV passent ensuite par des tickets. Le bon modèle dépend du parcours d'achat, pas de l'outil.

Les pipelines

Les transactions et les tickets avancent dans des pipelines, dont le nombre dépend de l'abonnement et du modèle de facturation du compte. Le pipeline par défaut de chaque objet ne compte pas. Un deuxième pipeline de transactions — pour séparer la vente neuve du renouvellement, par exemple — suppose donc au moins Starter.

L'API : ce qu'il faut prévoir côté intégration

Le versionnage est désormais daté. Depuis mars 2026, les chemins de l'API portent une version de la forme 2026-03, publiée deux fois par an et supportée au moins dix-huit mois (le détail dans la veille). Les anciennes API v1 à v3 cesseront d'être supportées en septembre 2027 : une intégration écrite il y a quelques années est probablement concernée.

Les quotas dépendent de l'abonnement, pour une application privée :

Le plafond quotidien est partagé entre toutes les applications du compte. Une reprise d'historique lancée le même jour qu'une synchronisation courante consomme le même budget : on l'étale, ou on la lance un week-end.

Avant de brancher quoi que ce soit

Cinq décisions à écrire, une ligne chacune, avant le premier scénario :

1. Quel objet porte quoi. Commande ou transaction ; ticket ou note ; objet standard ou personnalisé.
2. La clé de chaque objet. E-mail pour les contacts ; domaine, SIREN ou identifiant externe pour les entreprises — avec une propriété à valeur unique.
3. Qui fait foi, champ par champ. Quand Shopify et HubSpot écrivent tous deux l'adresse d'un client, l'un des deux gagne : décidez lequel.
4. Les associations attendues. Et ce qui se passe quand un contact en a plusieurs.
5. L'abonnement que ça suppose. Dix propriétés personnalisées en gratuit, les libellés en Professional, les objets personnalisés en Enterprise.

Ce sont ces cinq lignes qui permettent, deux ans plus tard, de changer d'outil ou de prestataire sans tout reconstruire. Pour les poser avec quelqu'un qui l'a déjà fait : mes interventions d'expert HubSpot. Pour le cas Shopify en particulier, les quatre façons de connecter Shopify et HubSpot.