Artikel

In HubSpot sind Artikel einzelne Instanzen von Produkten. Wenn ein Produkt einem Deal zugeordnet wird, wird es zu einem Artikel. Sie können Artikel erstellen, die eindeutig für ein einzelnes Angebot sind. Diese werden jedoch nicht zu Ihrer Produktbibliothek hinzugefügt. Die Artikel-Endpunkte ermöglichen es Ihnen, diese Daten zu verwalten und zwischen HubSpot und anderen Systemen zu synchronisieren.

Anwendungsfall als Beispiel: Wenn Sie eine Reihe von Angeboten für Vertriebsmitarbeiter erstellen, die an potenzielle Käufer gesendet werden sollen, können Sie diese API verwenden, um eigenständige Artikel pro Angebot sowie Artikel zu erstellen, die an bestehende Produkte angehängt werden.

Einen Artikel erstellen

Um einen eigenständigen Artikel zu erstellen, nehmen Sie eine POST-Anfrage an /crm/v3/objects/line_item vor. Geben Sie im Beitragstext die Details des Artikels an, z. B. Name, Menge und Preis.

Um ein Artikel basierend auf einem vorhandenen Produkt zu erstellen (erstellt über die Produkte-API oder in HubSpot), fügen Sie hs_product_id in den Beitragstext ein. 

Sie können den Artikel auch mit Deals, Angeboten, Rechnungen, Zahlungslinks oder Abonnements verknüpfen, indem Sie ein associations-Array in den Beitragstext einfügen. Zum Beispiel würde der Beitragstext unten ein Artikel namens „New standalone line item“ (Neuer eigenständiger Artikel) erstellen, der einem Deal (ID: 12345) zugeordnet ist.

// POST request to https://api.hubapi.com/crm/v3/objects/line_item { "properties": { "price": 10, "quantity": 1, "name": "New standalone line item" }, "associations": [ { "to": { "id": 12345 }, "types": [ { "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 20 } ]

Bitte beachten:

  • Artikel gehören zu einem einzelnen übergeordneten Objekt. Wenn Objekte zugeordnet werden, sollten Artikel für jedes Objekt individuell sein. Wenn Sie beispielsweise einen Deal und ein Angebot erstellen, sollten Sie einen Satz von Artikeln für den Deal und einen anderen Satz für das Angebot erstellen. Dies trägt dazu bei, CRM-Daten über Objekte hinweg zu optimieren und unerwarteten Datenverlust zu verhindern, wenn Artikel geändert werden müssen (z. B. werden durch das Löschen eines Angebots die Artikel des Angebots gelöscht, und wenn diese Artikel mit einem Deal verknüpft sind, werden auch die Deal-Artikel gelöscht).
  • Der im Feld Eigenschaften angegebene Preis darf nicht negativ sein.
  • Die Laufzeiteigenschaft des Artikels (hs_recurring_billing_period) akzeptiert die ISO-8601-Zeitraumformate PnYnMnD und PnW.

Einen Artikel abrufen

Sie können Artikel einzeln oder mehrere gleichzeitig abrufen.

  • Um ein bestimmtes Artikel abzurufen, führen Sie eine GET-Anfrage an /crm/v3/objects/line_items/{lineItemId} durch, wobei lineItemId die ID des Artikels ist.
  • Um alle Artikel abzurufen, führden Sie eine GET-Anfrage an /crm/v3/objects/line_items durch. 
In die Anfrage-URL können Sie die folgenden Parameter einschließen:
Use this table to describe parameters / fields
ParameterDescription
properties

Eine durch Kommas getrennte Liste der Eigenschaften, die in der Antwort zurückgegeben werden sollen. Wenn eine der angegebenen Eigenschaften in dem/den angefragten Objekt(en) nicht vorhanden ist, wird sie ignoriert.

propertiesWithHistory

Eine durch Kommas getrennte Liste der Eigenschaften, die zusammen mit ihrem Verlauf an vorherigen Werten zurückgegeben werden sollen. Wenn eine der angegebenen Eigenschaften in dem/den angefragten Objekt(en) nicht vorhanden ist, wird sie ignoriert.

Einen Artikel aktualisieren

Um einen Artikel zu aktualisieren, führen Sie eine PATCH-Anfrage an /crm/v3/objects/line_items/{lineItemId} durch, wobei lineItemId die ID des Artikels ist.

Schließen Sie im Text des Beitrags die Eigenschaftswerte ein, die Sie aktualisieren möchten. Sie können keine Zuordnungen über dieses Verfahren aktualisieren. Stattdessen müssen Sie die Zuordnungen-API verwenden.

Ihr Anfragetext kann beispielsweise wie folgt aussehen:

// PATCH request to https://api.hubapi.com/crm/v3/objects/line_item/{lineItemId} { "properties": { "price": 25, "quantity": 3, "name": "Updated line item" }

Einen Artikel löschen

Um einen Artikel zu löschen, führen Sie eine DELETE-Anfrage an /crm/v3/objects/line_items/{lineItemId} durch, wobei lineItemId die ID des Artikels ist.

Artikeleigenschaften

Wenn Sie Ihre Artikeldaten verwalten, möchten Sie möglicherweise einige der allgemeinen Eigenschaften in der folgenden Tabelle verwenden. Um alle Artikeleigenschaften abzurufen, führen Sie eine GET-Anfrage an /crm/v3/properties/line_item durch. Erfahren Sie mehr über die Verwendung der Eigenschaften-API.

Eigenschaftsname Label in UI Beschreibung
name Name Der Name des Artikels.
description Beschreibung Ausführliche Beschreibung des Produkts
hs_sku Bestandseinheit Eindeutige Produkt-ID
hs_billing_period_start_date Startdatum der Abrechnung Startdatum eines festen Abrechnungszeitraums
hs_billing_period_end_date Abrechnungsenddatum Enddatum eines festen Abrechnungszeitraums
recurringbillingfrequency Abrechnungsfrequenz Wie oft ein Artikel mit wiederkehrender Abrechnung abgerechnet wird. Es informiert über die Preiskalkulation für Deals und Angebote. Artikel mit einmaliger Abrechnung sind nicht enthalten.
quantity,
Menge Wie viele Einheiten eines Produkts sind in diesem Artikel enthalten
price
Einzelpreis Die Kosten des Produkts
amount Nettopreis Die Gesamtkosten des Artikels (d. h. die Menge multipliziert mit dem Einheitenpreis).
currency Währung Währungscode für den Artikel

War dieser Artikel hilfreich?
Dieses Formular dient dazu, Feedback zu unserer Entwicklerdokumentation zu sammeln. Wenn Sie uns Ihre Meinung zu HubSpot-Produkten mitteilen möchten, teilen Sie diese bitte im Ideenforum der Community.