API du CRM | Lignes de produit

Run in Postman

Exigences de portée

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ètre	Description
`properties`	Une 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.
`propertiesWithHistory`	Une 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 utilisateur	Description
`name`	Nom	Le nom de la ligne de produit
`description`	Description	Description complète du produit
`hs_sku`	SKU	Identifiant de produit unique
`hs_recurring_billing_start_date`	Date de début de facturation	Date de début de facturation récurrente pour une ligne de produit
`hs_recurring_billing_end_date`	Date de fin de facturation	Date de fin de facturation récurrente pour un article
`recurringbillingfrequency`	Fréquence de facturation	La 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.
`quantity`	Quantité	Combien d’unités d’un produit sont incluses dans cette ligne de produit
`price`	Prix unitaire	Le coût du produit
`amount`	Prix net	Le coût total de la ligne de produit (c’est-à-dire la quantité multipliée par le prix unitaire)
`hs_line_item_currency_code`	Devise	Code 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
`name`	Le descripteur interne du taux d’imposition.
`percentageRate`	La valeur du taux d’imposition, exprimée en pourcentage.
`label`	Le descripteur du taux d’imposition destiné à l’acheteur, affiché sur le devis, la facture ou d’autres objets parents.
`active`	Un 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.
`id`	L’ID du taux d’imposition.
`createdAt`	Un horodatage ISO 8601 indiquant la date de création du taux d’imposition.
`updatedAt`	Un 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.

Compte et paramètres

Gestion des applications

Authentification

Automatisation

CMS

Préférences de communication

Conversations

CRM

Data Studio

Événements

Fichiers

Marketing

Rendez-vous

Chiffre d'affaires

Webhooks

Journal des webhooks

API du CRM | Lignes de produit

Run in Postman

Exigences des domaines

Créer une ligne de produit

Remarque :

Récupérer une ligne de produit

Mettre à jour une ligne de produit

Supprimer une ligne de produit

Propriétés des lignes de produit

Récupérer les taux d’imposition

Run in Postman

​Exigences des domaines

​Créer une ligne de produit

​Remarque :

​Récupérer une ligne de produit

​Mettre à jour une ligne de produit

​Supprimer une ligne de produit

​Propriétés des lignes de produit

​Récupérer les taux d’imposition

Exigences des domaines

Créer une ligne de produit

Remarque :

Récupérer une ligne de produit

Mettre à jour une ligne de produit

Supprimer une ligne de produit

Propriétés des lignes de produit

Récupérer les taux d’imposition