HubSpot CRM の Line Items（商品項目）API について整理します。Line Items は製品（Product）が取引（Deal）や見積もり（Quote）に紐付けられたときに生成される個別のインスタンスです。

Line Items とは

HubSpot における Line Items は、製品カタログ（Products）とは異なる概念です。

  • Product: 製品カタログ上のマスターデータ
  • Line Item: Product が取引・見積もりなどに追加された際の個別インスタンス

Line Items への変更は元の Product には影響しません。取引ごとに価格や数量をカスタマイズできます。

API エンドポイント

ベース URL: /crm/v3/objects/line_items

操作メソッドエンドポイント
作成POST/crm/v3/objects/line_items
個別取得GET/crm/v3/objects/line_items/{lineItemId}
一覧取得GET/crm/v3/objects/line_items
更新PATCH/crm/v3/objects/line_items/{lineItemId}
削除DELETE/crm/v3/objects/line_items/{lineItemId}

必要なスコープ

スコープ用途
crm.objects.line_items.readデータ取得
crm.objects.line_items.write作成・更新
tax_rates.read税率情報の取得

データモデル詳細

Line Item の全プロパティは GET /crm/v3/properties/line_item で取得できます。以下はカテゴリ別の主要プロパティです。

基本情報

内部名表示名説明備考
name名前商品項目の名前必須
description説明製品の詳細な説明
hs_skuSKU製品の固有識別子
hs_product_id製品 ID関連する製品ライブラリの ID製品から作成時に指定
hs_object_idレコード IDLine Item の一意な ID自動設定・読み取り専用
hs_product_type製品タイプINVENTORY（在庫）/ NON_INVENTORY（非在庫）/ SERVICE（サービス）
hs_urlURL製品の Web ページ URL
hs_images画像 URL製品画像の URL

価格・数量

内部名表示名説明備考
quantity数量含まれる製品の単位数
price単価購入者向けの製品単価負の値は不可
amount正価（Net price）合計金額（数量 × 単価）計算フィールド
hs_cost_of_goods_sold売上原価製品の原価
hs_line_item_currency_code通貨通貨コード（例: JPY, USD）
hs_pricing_model価格モデルFLAT（定額）または TIERED（段階制）
hs_effective_unit_price有効単価段階制価格の場合に適用される実効単価

割引

内部名表示名説明備考
hs_discount_percentage割引率適用される割引の割合（%）
discount単位割引額単位あたりの割引金額
hs_total_discount合計割引額割引率と割引金額を考慮した総割引額計算フィールド
hs_pre_discount_amount割引前金額割引適用前の金額計算フィールド

税金

内部名表示名説明備考
hs_tax_rate_group_id税率グループ ID適用する税率の識別子
tax税額適用される税金額
hs_tax_amount計算税額税率から自動計算された税額計算フィールド
hs_tax_rate税率適用される税率（%）
hs_after_tax_amount税込金額税額適用後の金額計算フィールド

定期請求（Recurring Billing）

内部名表示名説明備考
recurringbillingfrequency請求頻度定期請求の頻度（monthly, quarterly, annually など）
hs_recurring_billing_period請求期間ISO-8601 期間形式（例: P12M = 12ヶ月, P1Y = 1年）PnYnMnD / PnW 形式
hs_recurring_billing_start_date請求開始日定期請求の開始日
hs_recurring_billing_end_date請求終了日定期請求の終了日
hs_recurring_billing_terms請求条件FIXED（固定回数）または AUTO_RENEW（自動更新）
hs_recurring_billing_number_of_payments支払い回数固定回数請求の場合の支払い総数
hs_billing_start_delay_days請求開始遅延（日）請求開始を遅延させる日数
hs_billing_start_delay_months請求開始遅延（月）請求開始を遅延させる月数
hs_billing_start_delay_type請求遅延タイプFIXED_DATE（固定日）または DELAYED_PERIOD（遅延期間）
hs_term_in_months期間（月）契約期間の月数

収益指標（計算フィールド）

内部名表示名説明
hs_tcv総契約額（TCV）Total Contract Value
hs_acv年間契約額（ACV）Annual Contract Value
hs_arr年間経常収益（ARR）Annual Recurring Revenue
hs_mrr月間経常収益（MRR）Monthly Recurring Revenue
hs_marginマージン売上 − 売上原価
hs_margin_tcvマージン TCVTCV − 売上原価合計
hs_margin_acvマージン ACVACV − 売上原価（年間）
hs_margin_arrマージン ARRARR − 売上原価（年間）
hs_margin_mrrマージン MRRMRR − 売上原価（月間）

システムプロパティ（読み取り専用）

内部名表示名説明
createdate作成日時レコード作成日時
hs_lastmodifieddate最終更新日時プロパティが最後に変更された日時
hs_created_by_user_id作成者ユーザー IDレコードを作成したユーザー
hs_updated_by_user_id更新者ユーザー ID最後に更新したユーザー
hs_object_sourceレコードソースレコードの作成方法
hs_was_importedインポートフラグインポートによって作成されたかどうか

プロパティの種別

  • 必須: name のみが作成時に必須。ただし price と quantity も通常は指定する
  • 計算フィールド: amount, hs_total_discount, hs_pre_discount_amount, hs_after_tax_amount, hs_tax_amount, 収益指標（TCV/ACV/ARR/MRR）は HubSpot が自動計算する。API から直接設定はできない
  • 読み取り専用: システムプロパティ（作成日時、更新日時、ユーザー ID 等）は自動設定される
  • price の制約: 負の値を設定できない

Line Item の作成例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

POST /crm/v3/objects/line_items

{
  "properties": {
    "name": "Web開発サービス",
    "hs_product_id": "12345",
    "quantity": "1",
    "price": "500000"
  }
}

取引や見積もりへの関連付けを同時に行う場合は、後述の「関連付け」セクションを参照してください。

関連付け（Associations）

Line Items は以下のオブジェクトと関連付けできます。

関連先Line Item → 関連先関連先 → Line Item
取引（Deals）2019
見積もり（Quotes）68—
請求書（Invoices）410—
支払いリンク（Payment Links）——
サブスクリプション（Subscriptions）——

取引への関連付け例

方法 1: Line Item 作成時に関連付ける

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

POST /crm/v3/objects/line_items

{
  "properties": {
    "name": "Web開発サービス",
    "hs_product_id": "12345",
    "quantity": "1",
    "price": "500000"
  },
  "associations": [
    {
      "to": { "id": "67890" },
      "types": [
        {
          "associationCategory": "HUBSPOT_DEFINED",
          "associationTypeId": 20
        }
      ]
    }
  ]
}

方法 2: 既存の Line Item を取引に関連付ける（Associations v4 API）

既に作成済みの Line Item を取引に紐付けるには、Associations API を使用します。

PUT /crm/v4/objects/line_items/{lineItemId}/associations/default/deals/{dealId}

ラベル付き関連付けを指定する場合:

1
2
3
4
5
6
7
8

PUT /crm/v4/objects/line_items/{lineItemId}/associations/deals/{dealId}

[
  {
    "associationCategory": "HUBSPOT_DEFINED",
    "associationTypeId": 20
  }
]

方法 3: 一括関連付け（バッチ）

複数の Line Item をまとめて関連付けるには、バッチエンドポイントを使用します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

POST /crm/v4/associations/line_items/deals/batch/create

{
  "inputs": [
    {
      "from": { "id": "100001" },
      "to": { "id": "67890" },
      "types": [
        {
          "associationCategory": "HUBSPOT_DEFINED",
          "associationTypeId": 20
        }
      ]
    },
    {
      "from": { "id": "100002" },
      "to": { "id": "67890" },
      "types": [
        {
          "associationCategory": "HUBSPOT_DEFINED",
          "associationTypeId": 20
        }
      ]
    }
  ]
}

重要な制限

Line Items は 1 つの親オブジェクトにのみ属します。 同じ Line Item を複数の取引や見積もりに共有することはできません。複数のオブジェクトに同じ製品を紐付けたい場合は、オブジェクトごとに別々の Line Item を作成する必要があります。

カスタムプロパティで備考情報を追加する

デフォルトの description は製品説明用のため、Line Item ごとの備考にはカスタムプロパティを作成するのが実用的です。

API でカスタムプロパティを作成

1
2
3
4
5
6
7
8
9

POST /crm/v3/properties/line_items

{
  "name": "notes",
  "label": "備考",
  "type": "string",
  "fieldType": "textarea",
  "groupName": "lineiteminformation"
}

主な fieldType の選択肢:

fieldType用途
text単行テキスト
textarea複数行テキスト（備考向き）
number数値
date日付
selectドロップダウン選択

Line Item 作成・更新時に備考を設定

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

POST /crm/v3/objects/line_items

{
  "properties": {
    "name": "Web開発サービス",
    "price": "500000",
    "quantity": "1",
    "notes": "初回割引適用。契約更新時に見直し予定。"
  }
}

カスタムプロパティは HubSpot UI の 設定 → プロパティ → 商品項目 からも作成・管理できます。

参考リンク