Zum Hauptinhalt springen

Run in Postman
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.

​
Anforderungen an den Bereich

Basierend auf den Endpunkten, die Sie verwenden möchten, müssen Sie die folgenden Bereiche autorisieren:
  • crm.objects.line_items.read: Ermöglicht Zugriff auf das Abrufen von Artikeldaten.
  • crm.objects.line_items.write: Ermöglicht Zugriff auf das Erstellen und Aktualisieren von Artikeln.
  • tax_rates.read: Ermöglicht Zugriff auf den Abruf von Steuersätzen, die Sie in Ihrem Account konfiguriert haben.

​
Einen Artikel erstellen

Um einen eigenständigen Artikel zu erstellen, nehmen Sie eine POST-Anfrage an /crm/v3/objects/line_items vor. Geben Sie im Beitragstext die Details des Artikels an, z. B. Name, Menge und Preis. Sie können auch zusätzliche Daten in den Anforderungstext aufnehmen:
  • Um einen 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.
  • Um den Steuersatz für Ihren Artikel einzuschließen, geben Sie seine ID als hs_tax_rate_group_id im properties-Feld des Anforderungstextes an.
  • 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 einen Artikel namens „New standalone line item“ (Neuer eigenständiger Artikel) erstellen, der einem Deal (ID: 12345) zugeordnet ist.
{
  "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
        }
      ]
    }
  ]
}

​
Hinweis:

  • 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 properties-Feld angegebene price 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 einen bestimmten 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ühren Sie eine GET-Anfrage an /crm/v3/objects/line_items durch.
In die Anfrage-URL können Sie die folgenden Parameter einschließen:
ParameterBeschreibung
propertiesEine 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.
propertiesWithHistoryEine 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 Anforderungstext kann beispielsweise wie folgt aussehen: 
{
  "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. Hier erfahren Sie mehr über die Verwendung der Eigenschaften-API.
EigenschaftsnameLabel in UIBeschreibung
nameNameDer Name des Artikels
descriptionBeschreibungAusführliche Beschreibung des Produkts
hs_skuBestandseinheitEindeutige Produkt-ID
hs_recurring_billing_start_dateAbrechnungsstartdatumStartdatum bei wiederkehrender Abrechnung für einen Artikel
hs_recurring_billing_end_dateAbrechnungsenddatumEnddatum bei wiederkehrender Abrechnung für einen Artikel
recurringbillingfrequencyAbrechnungsfrequenzWie oft ein Artikel mit wiederkehrender Abrechnung abgerechnet wird. Dies informiert über die Preiskalkulation für Deals und Angebote. Artikel mit einmaliger Abrechnung sind nicht enthalten.
quantityMengeWie viele Einheiten eines Produkts in diesem Artikel enthalten sind
priceEinzelpreisDie Kosten des Produkts
amountNettopreisDie Gesamtkosten des Artikels (d. h., die Menge multipliziert mit dem Einheitenpreis)
hs_line_item_currency_codeWährungWährungscode für den Artikel

​
Steuersätze abrufen

Sie können einen Steuersatz auf einzelne Artikel anwenden (z. B. die Umsatzsteuer von 6,25 % im Bundesstaat Massachusetts). Nachdem Sie Ihre Steuersatzbibliothek in Ihrem HubSpot-Account konfiguriert haben, können Sie eine GET-Anfrage an /tax-rates/v1/tax-rates vornehmen, um alle Steuersätze abzurufen, oder an /tax-rates/v1/tax-rates/{taxRateId}, um einen Steuersatz anhand seiner ID abzurufen. Ihre App muss den tax_rates.read-Bereich autorisieren, um diese Anfrage vorzunehmen. Die resultierende Antwort sieht etwa so aus: 
{
  "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"
}
Jedes Steuersatz-Objekt enthält die folgenden Eigenschaften:
EigenschaftstypBeschreibung
nameDer interne Deskriptor für den Steuersatz
percentageRateDie Höhe des Steuersatzes in Prozent
labelDer dem Käufer angezeigte Deskriptor des Steuersatzes, der in dem Angebot, der Rechnung oder anderen übergeordneten Objekten angezeigt wird
activeEin boolescher Wert, der angibt, ob der Steuersatz auf ein neues Angebot oder eine neue Rechnung angewendet werden kann. Sie könnten z. B. den Steuersatz eines früheren Jahres, der nicht mehr anwendbar ist, als false festlegen.
idDie ID des Steuersatzes
createdAtEin ISO 8601-Zeitstempel, der angibt, wann der Steuersatz erstellt wurde
updatedAtEin ISO 8601-Zeitstempel, der angibt, wann der Steuersatz zuletzt aktualisiert wurde
Sobald Sie die ID für den Steuersatz haben, den Sie anwenden möchten, geben Sie die id für die hs_tax_rate_group_id im properties-Feld an, wenn Sie einen Artikel erstellen. Erfahren Sie im Abschnitt weiter oben mehr über das Erstellen von Artikeln.
Last modified on December 10, 2025