最終更新日: 2025年8月22日

Run in Postman

 HubSpotにおいて商品項目は、製品の個々のインスタンスです。製品は取引に紐付けられると、商品項目になります。個別の見積もり上に作成した商品項目は、製品ライブラリーには追加されません。商品項目エンドポイントを使用することにより、商品項目データを管理したり、HubSpotと他のシステムとの間で同期したりできます。 使用例: 営業担当者から潜在顧客に送信するための見積もり一式を作成する際に、商品項目APIを使用して、見積もりごとにスタンドアロンの商品項目ならびに既存の製品に関連付けられた商品項目を作成できます。

​
スコープの要件

使用するエンドポイントに基づいて、次のスコープを承認する必要があります。
  • crm.objects.line_items.read：商品項目データを取得するためのアクセス権を提供します。
  • crm.objects.line_items.write：商品項目を作成および更新するためのアクセス権を提供します。
  • tax_rates.read：アカウントで設定した税率を取得するためのアクセス権を提供します。

​
商品項目を作成する

商品項目を作成するには、POSTリクエストを/crm/v3/objects/line_itemsに送信します。POSTリクエスト本文に、商品項目の詳細（名前、数量、価格など）を含めます。リクエスト本文に追加のデータを含めることもできます。
  • 既存の製品（製品APIを使用して作成された、またはHubSpot内で作成された）に基づく商品項目を作成するには、POSTリクエスト本文にhs_product_idを含めます。
  • 商品項目の税率を含めるには、リクエスト本文のpropertiesフィールドにIDをhs_tax_rate_group_idとして含めます。
  • POSTリクエスト本文にassociations配列を含めることで、商品項目を取引、見積もり、請求書、支払いリンク、サブスクリプションに関連付けることも可能です。例えば、以下のような本文でPOSTリクエストを送信すると、取引（ID：12345）が関連付けられた「New standalone line item」という名前の商品項目が作成されます。
{
  "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
        }
      ]
    }
  ]
}

​
注：

  • 商品項目は、1つの単一親オブジェクトに属します。オブジェクトを関連付ける場合、商品項目はラインアイテムはオブジェクトごとに個別にする必要があります。例えば取引と見積もりを作成する場合は、取引用に1つの商品項目セットを作成し、見積もり用に別の商品項目セットを作成する必要があります。これは、オブジェクト間でCRMデータを合理化し、商品項目を変更する必要があるときに予期しないデータ損失が発生しないようにするのに役立ちます（例えば、見積もりを削除すると見積もりの商品項目が削除され、それらの商品項目が取引に関連付けられている場合には、取引の商品項目も削除されます）。
  • propertiesフィールド内で指定されたpriceを負の値にすることはできません。
  • 商品項目の［期間］プロパティー（hs_recurring_billing_period）では、ISO-8601の期間形式のPnYnMnDおよびPnWを使用できます。_ _

​
商品項目を取得する

商品項目を個別に、または一括で取得できます。
  • 特定の商品項目を取得するには、GETリクエストを/crm/v3/objects/line_items/{lineItemId}に送信します。lineItemIdは商品項目のIDを指します。
  • 全ての商品項目を取得するには、GETリクエストを/crm/v3/objects/line_itemsに送信します。
リクエストのURLには、次のパラメーターを含めることができます。
パラメーター説明
propertiesレスポンスで返されるプロパティーのカンマ区切りリスト。指定したプロパティーのいずれかがリクエスト対象のオブジェクトに存在しない場合、これらのプロパティーは無視されます。
propertiesWithHistory以前の値の履歴と併せて取得するプロパティーのカンマ区切りのリスト。指定したプロパティーのいずれかがリクエスト対象のオブジェクトに存在しない場合、これらのプロパティーは無視されます。

​
商品項目を更新する

商品項目を更新するには、PATCHリクエストを/crm/v3/objects/line_items/{lineItemId}に送信します。lineItemIdは商品項目のIDを指します。 リクエスト本文に、更新するプロパティー値を含めます。このメソッドを使用して関連付けを更新することはできません。代わりに、関連付けAPIを使用する必要があります。 例えば、リクエスト本文は次のようになります。 
{
  "properties": {
    "price": 25,
    "quantity": 3,
    "name": "Updated line item"
  }
}

​
商品項目を削除する

商品項目を削除するには、DELETEリクエストを/crm/v3/objects/line_items/{lineItemId}に送信します。lineItemIdは商品項目のIDを指します。

​
商品項目のプロパティー

商品項目データを管理する場合は、以下の表に示す一般的なプロパティーのいくつかを使用することをお勧めします。全ての商品項目プロパティーを取得するには、GETリクエストを/crm/v3/properties/line_itemに送信します。プロパティーAPIの使用について詳細をご確認ください。
プロパティー名UIのラベル説明
name名前商品項目の名前
description説明製品の詳細な説明
hs_skuSKU製品の固有ID
hs_recurring_billing_start_date請求開始日商品項目の定期請求開始日
hs_recurring_billing_end_date請求終了日商品項目の定期請求終了日
recurringbillingfrequency請求の頻度定期請求がある商品項目の請求頻度。取引および見積もりの価格計算の情報が取得されます。1回限りの請求がある商品項目は含まれていません。
quantity数量この商品項目に含まれる製品の単位数
price単価製品のコスト
amount正価商品項目の合計コスト（数量×単価）。
hs_line_item_currency_code通貨商品項目の通貨コード

​
税率を取得する

各商品項目に税率を適用できます（例：マサチューセッツ州の売上税6.26％）。HubSpotアカウントで税率ライブラリーを設定したら、GETリクエストを/tax-rates/v1/tax-ratesへ送信して全ての税率を取得するか、/tax-rates/v1/tax-rates/{taxRateId}へ送信してIDを基準にした税率を取得できます。このリクエストを行うには、アプリでtax_rates.readスコープが承認されている必要があります。 結果の応答は、次のようになります。 
{
  "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"
}
各税率オブジェクトには、次のプロパティーが含まれます。
プロパティータイプ説明
name税率の内部記述子。
percentageRateパーセントで表される税率の値。
label購入者に表示される税率の説明子。見積もり、請求書、またはその他の親オブジェクトに表示されます。
active税率を新しい見積もりまたは請求書に適用できるかどうかを示すブール値。これは、適用されなくなった前年度の税率に対してfalseに設定することもできます。
id税率のID。
createdAt税率の作成時期を示すISO 8601タイムスタンプ。
updatedAt税率が最後に更新された日付を示すISO 8601タイムスタンプ。
適用する税率のIDを取得したら、商品項目を作成する際にpropertiesフィールドにhs_tax_rate_group_idのidを指定します。商品項目の作成の詳細については、上記のセクションをご参照ください。