quote-to-cash

リソース

ファイル	使用するタイミング
resources/q2c-essentials.md	6 フィールドのチートシート、関連付けの方向、請求書・サブスクリプション・注文・カートに関するポータルの注意事項。

基礎

まず bulk-operations/SKILL.md を読んでください。JSONL のパイプ処理、バッチ読み取り、ページネーション、および破壊的操作のためのドライラン／ダイジェスト／確認のフローはそこに記載されています。再整形レシピ（読み取り → 書き込みペイロード）は bulk-operations/resources/json-patterns.md にあります。

hubspot <command> --help が信頼できる情報源です。オブジェクトタイプは複数形です（products、line_items、quotes、invoices、subscriptions）。プロパティテーブルをハードコードしないでください。hubspot properties list --type <type> は 1 回の呼び出しで済みます。エージェントが書き込もうとしている列挙値は、hubspot properties options-list --type <type> <property> | jq -r '.value' で必ず確認してください。

ポータルに関する注意: invoices、subscriptions、orders、carts は hubspot objects types で空の objectTypeId を表示します。これらはトークンが一致するスコープ（invoices-read、subscriptions-read など）を持っている場合は objects search／list を通じて機能し、そうでなければ 403 になります。CLI で作成された見積は常に DRAFT です。承認ルーティング、共有リンク、PDF 生成、請求書作成には通常 HubSpot UI が必要です。

1. 製品を作成する

hubspot objects create --type products \
  --property name="Enterprise License" \
  --property price=12000 \
  --property hs_sku=ENT-001

定期製品の場合は recurringbillingfrequency を設定します。まず hubspot properties options-list --type products recurringbillingfrequency | jq -r '.value' で API の列挙値を確認してください。{"properties":{...}} の JSONL を hubspot objects create --type products --dry-run にパイプすることで、カタログを一括インポートできます。

2. 見積を構築する: 明細項目 → 見積 → 関連付け

objects create は stdin の行ごとに 1 行の結果を、入力順に出力します。これにより、3 つのパイプで明細項目を作成し、その ID を取得し、新しい見積に関連付けることができます。レコードごとのシェルループは不要です。

DEAL_ID=12345

# 1. Create the line items. items.jsonl holds {"name":..,"qty":..,"price":..,"product_id":..} per line.
jq -c '{properties:{
    name:.name, quantity:(.qty|tostring), price:(.price|tostring),
    hs_product_id:.product_id, hs_line_item_currency_code:"USD"
  }}' items.jsonl \
| hubspot objects create --type line_items > /tmp/lineitems.jsonl

# 2. Create the quote.
QUOTE_ID=$(hubspot objects create --type quotes \
  --property hs_title="Acme Corp - 2026" \
  --property hs_expiration_date=2026-06-30 \
  --property hs_currency=USD \
  --format json | jq -r '.data.id // .id')

# 3. Associate every new line item to the quote in one pipe.
jq -r '.id' /tmp/lineitems.jsonl \
| jq -cR --arg q "$QUOTE_ID" '{from:("quotes:" + $q), to:("line_items:" + .)}' \
| hubspot associations create

# 4. Link the quote to the deal.
hubspot associations create --from "deals:$DEAL_ID" --to "quotes:$QUOTE_ID"

割引の扱い — discount は書き込み可能なパーセンテージです（10 は 10% オフ）。hs_total_discount は HubSpot が計算するものであり、設定しないでください。所有していないポータルでこれに依存する前に、hubspot properties get --type line_items hs_total_discount で確認してください（プロパティ名は位置引数です。modificationMetadata.readOnlyValue:true を探してください）。

共有する準備ができたら、見積を DRAFT から昇格させます。objects update は不可逆です。まずドライランを実行し、次にダイジェストと --confirm <quote_id> を付けて再実行してください:

hubspot objects update --type quotes <quote_id> --property hs_status=APPROVAL_NOT_NEEDED --dry-run
hubspot objects update --type quotes <quote_id> --property hs_status=APPROVAL_NOT_NEEDED --digest <hash> --confirm <quote_id>

ポータルの hs_status 列挙値を確認してください: hubspot properties options-list --type quotes hs_status | jq -r '.value'。

3. 請求書を追跡する

CLI は請求書データを読み取り、ステータスを更新します。作成には通常 HubSpot Commerce + UI が必要です。hs_invoice_status と日付でフィルタリングしてください。

# All outstanding invoices
hubspot objects search --type invoices \
  --filter "hs_invoice_status=OUTSTANDING" \
  --properties hs_number,hs_amount_billed,hs_balance,hs_due_date

# Past-due (overdue) invoices, dynamic date
hubspot objects search --type invoices \
  --filter "hs_due_date<$(date +%Y-%m-%d) AND hs_invoice_status!=PAID" \
  --properties hs_number,hs_due_date,hs_balance

# Invoices billed in the last 30 days
hubspot objects search --type invoices \
  --filter "hs_invoice_date>=$(date -v-30d +%Y-%m-%d 2>/dev/null || date -d '30 days ago' +%Y-%m-%d)" \
  --properties hs_number,hs_amount_billed,hs_invoice_date

ステータスの列挙値も同じ方法で確認してください: hubspot properties options-list --type invoices hs_invoice_status | jq -r '.value'。

4. サブスクリプションを追跡する

同じ形式で、hs_subscription_status でフィルタリングします。フィルターを書く前に列挙値を確認してください。ACTIVE／CANCELLED／PAST_DUE をハードコードしないでください:

hubspot properties options-list --type subscriptions hs_subscription_status | jq -r '.value'

# Then filter (case matters)
hubspot objects search --type subscriptions \
  --filter "hs_subscription_status=<value-from-above>" \
  --properties hs_mrr,hs_arr,hs_subscription_status

# Sum MRR across active subs
hubspot objects search --type subscriptions \
  --filter "hs_subscription_status=<active-value>" --format json \
  | jq '[.data[].properties.hs_mrr | select(. != null and . != "") | tonumber] | add // 0'

既知の制約

• invoices、subscriptions、orders、carts、payments は、アクティブなトークンに一致する読み取りスコープが必要です。403 は、ユーザーの OAuth ログインまたはプライベートアプリトークンにスコープが欠けていることを意味します。
• products／quotes／line_items に対する objects delete は、ユーザー OAuth（hubspot auth login、オブジェクトの書き込みスコープ付き）とサービスキー（export HUBSPOT_ACCESS_TOKEN=<token>）の両方で機能します。403 は、アクティブなトークンにその書き込みスコープが欠けていることを意味します。例外は --gdpr による完全削除で、これはサービスキーが必要です。GDPR エンドポイントはユーザー OAuth トークンを受け付けません。カタログレコードを一括削除する前のドライラン → ダイジェスト → 確認のフローについては bulk-operations/SKILL.md を参照してください。
• 見積の共有リンク、PDF 生成、承認ルーティング、およびゼロからの請求書作成は UI 専用です。CLI はレコードを更新できますが、見積を顧客に送信することはできません。
• 明細項目の hs_total_discount は読み取り専用です。代わりに discount（パーセンテージ）を設定してください。