Dernière modification : 22 août 2025

Run in Postman

 Dans HubSpot, les lignes de produit sont des instances individuelles de produits. Lorsqu’un produit est associé à une transaction, il devient une ligne de produit. Vous pouvez créer des lignes de produit propres à un devis, qui ne seront pas ajoutées à votre bibliothèque de produits. Les points de terminaison des lignes de produit vous permettent de gérer ces données et de les synchroniser entre HubSpot et d’autres systèmes. Exemple de cas d’utilisation : lors de la création d’un ensemble de devis que les représentants commerciaux enverront à de potentiels acheteurs, vous pouvez utiliser cette API pour créer des lignes de produit autonomes pour chaque devis ainsi que des lignes de produit associées à des produits existants.

​
Exigences des domaines

En fonction des points de terminaison que vous prévoyez d’utiliser, vous devrez autoriser les domaines suivants :
  • crm.objects.line_items.read : permet de récupérer les données de ligne de produit.
  • crm.objects.line_items.write : permet de créer et de mettre à jour des lignes de produits.
  • tax_rates.read : permet de récupérer les taux de taxe que vous avez configurés dans votre compte.

​
Créer une ligne de produit

Pour créer une ligne de produit, effectuez une requête POST à /crm/v3/objects/line_items. Dans le corps de l’article, incluez les détails de la ligne de produit, tels que le nom, la quantité et le prix. Vous pouvez également inclure des données supplémentaires dans le corps de la requête :
  • Pour créer une ligne de produit basée sur un produit existant (créé via l’API de produits ou dans HubSpot), incluez hs_product_id dans le corps de l’article.
  • Pour inclure le taux d’imposition de votre ligne de produit, indiquez son ID comme hs_tax_rate_group_id dans le champ properties du corps de la requête.
  • Vous pouvez également associer la ligne de produit avec des transactions, des devis, des factures, des liens de paiement ou des abonnements en incluant un tableau associations dans le corps de l’article. Par exemple, le corps d’article ci-dessous créerait une ligne de produit intitulée « Nouvelle ligne de produit autonome » associée à une transaction (ID : 12345).
{
  "properties": {
    "price": 10,
    "quantity": 1,
    "name": "New standalone line item",
    "hs_tax_rate_group_id": "2148420997"
  },
  "associations": [
    {
      "to": {
        "id": 12345
      },
      "types": [
        {
          "associationCategory": "HUBSPOT_DEFINED",
          "associationTypeId": 20
        }
      ]
    }
  ]
}

​
Remarque :

  • Les lignes de produit appartiennent à un seul objet parent. Si vous associez des objets, les lignes de produit doivent être individuelles à chaque objet. Par exemple, si vous créez une transaction et un devis, vous devez créer un ensemble de lignes de produit pour la transaction et un autre ensemble pour le devis. Cela aidera à rationaliser les données CRM entre les objets et à prévenir la perte de données inattendue lorsque vous devez modifier des lignes de produit (par exemple, la suppression d’un devis supprimera les lignes de produit du devis, et si ces lignes de produit sont associées à une transaction, les lignes de produit des transactions seront également supprimées).
  • La valeur price spécifiée dans le champ properties ne peut pas être négative.
  • La propriété Durée des lignes de produit (hs_recurring_billing_period) accepte les formats de période ISO-8601 de PnYnMnD et PnW.

​
Récupérer une ligne de produit

Vous pouvez récupérer des lignes de produit de façon individuelle ou en masse.
  • Pour récupérer une ligne de produit spécifique, effectuez une requête GET à /crm/v3/objects/line_items/{lineItemId} où lineItemId est l’ID de la ligne de produit.
  • Pour récupérer toutes les lignes de produit, effectuez une requête GET à /crm/v3/objects/line_items.
Vous pouvez inclure les paramètres suivants dans l’URL de la requête :
ParamètreDescription
propertiesUne liste séparée par des virgules des propriétés à renvoyer dans la réponse. Si l’une des propriétés spécifiées n’est pas présente sur les objets demandés, elle sera ignorée.
propertiesWithHistoryUne liste séparée par des virgules des propriétés à renvoyer avec un historique de leurs précédentes valeurs. Si l’une des propriétés spécifiées n’est pas présente sur les objets demandés, elle sera ignorée.

​
Mettre à jour une ligne de produit

Pour mettre à jour une ligne de produit, effectuez une requête PATCH à /crm/v3/objects/line_items/{lineItemId} où lineItemId est l’ID de la ligne de produit. Dans le corps d’article, incluez les valeurs de propriété que vous souhaitez mettre à jour. Vous ne pouvez pas mettre à jour des associations via cette méthode. Vous devrez plutôt utiliser l’API des associations. Par exemple, votre corps de requête peut ressembler aux éléments suivants : 
{
  "properties": {
    "price": 25,
    "quantity": 3,
    "name": "Updated line item"
  }
}

​
Supprimer une ligne de produit

Pour supprimer une ligne de produit, effectuez une requête DELETE à /crm/v3/objects/line_items/{lineItemId} où lineItemId est l’ID de la ligne de produit.

​
Propriétés des lignes de produit

Lors de la gestion de vos données de ligne de produit, vous pouvez utiliser certaines des propriétés communes dans le tableau ci-dessous. Pour obtenir toutes les propriétés des lignes de produit, effectuez une requête GET à /crm/v3/properties/line_item. Découvrez-en davantage sur l’utilisation de l’API des propriétés.
Nom de la propriétéLibellé dans l’interface utilisateurDescription
nameNomLe nom de la ligne de produit
descriptionDescriptionDescription complète du produit
hs_skuSKUIdentifiant de produit unique
hs_recurring_billing_start_dateDate de début de facturationDate de début de facturation récurrente pour une ligne de produit
hs_recurring_billing_end_dateDate de fin de facturationDate de fin de facturation récurrente pour un article
recurringbillingfrequencyFréquence de facturationLa fréquence à laquelle une ligne de produit avec facturation récurrente est facturé. Elle informe le calcul des prix pour les transactions et les devis. Les lignes de produit avec facturation unique ne sont pas incluses.
quantityQuantitéCombien d’unités d’un produit sont incluses dans cette ligne de produit
pricePrix unitaireLe coût du produit
amountPrix netLe coût total de la ligne de produit (c’est-à-dire la quantité multipliée par le prix unitaire)
hs_line_item_currency_codeDeviseCode de devise pour la ligne de produit

​
Récupérer les taux d’imposition

Vous pouvez appliquer un taux d’imposition à des lignes de produits individuelles (par exemple, une taxe sur les ventes de 6,26 % en Allemagne). Une fois que vous avez configuré votre bibliothèque de taux d’imposition dans votre compte HubSpot, vous pouvez faire une requête GET à /tax-rates/v1/tax-rates pour récupérer tous les taux d’imposition, ou /tax-rates/v1/tax-rates/{taxRateId} pour récupérer un taux d’imposition par son ID. Votre application devra autoriser la portée tax_rates.read à exécuter cette requête. La réponse sera au format suivant : 
{
  "name": "MA Sales tax 2025",
  "percentageRate": 6.25
  "label": "Sales Tax",
  "active": true,
  "id": "2148420997",
  "createdAt": "2024-12-12T23:20:39.923Z",
  "updatedAt": "2024-12-12T23:20:39.923Z"
}
Chaque objet de taux d’imposition comprendra les propriétés suivantes :
Type de propriétéDescription
nameLe descripteur interne du taux d’imposition.
percentageRateLa valeur du taux d’imposition, exprimée en pourcentage.
labelLe descripteur du taux d’imposition destiné à l’acheteur, affiché sur le devis, la facture ou d’autres objets parents.
activeUn booléen qui indique si le taux d’imposition peut être appliqué à un nouveau devis ou à une nouvelle facture. Vous pouvez définir false pour un taux d’imposition de l’année précédente qui n’est plus applicable.
idL’ID du taux d’imposition.
createdAtUn horodatage ISO 8601 indiquant la date de création du taux d’imposition.
updatedAtUn horodatage ISO 8601 indiquant la date de la dernière mise à jour du taux d’imposition.
Une fois que vous avez l’identifiant du taux d’imposition que vous souhaitez appliquer, indiquez ce id pour le hs_tax_rate_group_id dans le champ properties lors de la création d’une ligne de produit. Pour en savoir plus sur la création de lignes de produits, reportez-vous à la section ci-dessus.