customer-retention

リソース

ファイル	使用するタイミング
resources/customer-health-signals.md	チャーンシグナルのフィルタークックブック — notes_last_contacted、hs_last_sales_activity_date、hs_email_optout、滞留チケット、サブスクリプションステータスに対する --filter 式。

前提条件

まず bulk-operations/SKILL.md を読んでください。以下のすべての読み取り／書き込みは、その JSONL パイプ、ページネーション、ドライラン／ダイジェストのパターンを使用します。アクティビティプロパティのテーブルと関連付けのルールは sales-execution/SKILL.md にあります。

スキーマはポータルごとに異なります。フィルタリングの前に各プロパティを確認してください — 例: hubspot properties get --type contacts notes_last_contacted、... hs_last_sales_activity_date、... --type subscriptions hs_subscription_status。subscriptions が 403 を返す場合、トークンに subscriptions-read がありません — そのスコープを持つプライベートアプリのトークンを使用してください。

1 — 非アクティブな顧客を見つける

CUTOFF=$(date -v-60d +%Y-%m-%d 2>/dev/null || date -d '60 days ago' +%Y-%m-%d)

# No outreach in 60d (calls/notes/meetings update notes_last_contacted)
hubspot objects search --type contacts \
  --filter "lifecyclestage=customer AND notes_last_contacted<$CUTOFF" \
  --properties email,firstname,notes_last_contacted,hubspot_owner_id

# No sales activity in 60d (broader — also catches emails/tasks)
hubspot objects search --type contacts \
  --filter "lifecyclestage=customer AND hs_last_sales_activity_date<$CUTOFF" \
  --properties email,firstname,hs_last_sales_activity_date

# Never contacted
hubspot objects search --type contacts \
  --filter "lifecyclestage=customer AND !notes_last_contacted" \
  --properties email,firstname

その他のシグナル（メールのオプトアウト、滞留チケット、オープンな取引なし）については resources/customer-health-signals.md を参照してください。100 件を超えるヒットについては、bulk-operations のページネーションループを使用してください。

顧客がなぜチャーンしたか、またはステージを移動したか — どのワークフロー、連携、インポート、または UI 編集が最後に lifecyclestage を変更したか — を監査するには、hubspot objects history --type contacts --properties lifecyclestage [--id <recordId>] [--include-ui] を使用します。これは各プロパティのソース履歴を、変更ごとに 1 行に平坦化します。

2 — リスクのあるサブスクリプションにフラグを付ける

subscriptions は標準オブジェクトです（hubspot objects types で確認できます）。hs_subscription_status の列挙値はポータルごとに異なります — フィルタリングの前に確認し、正確な値を入力してください:

hubspot properties options-list --type subscriptions hs_subscription_status   # allowed values

# Past-due — revenue at immediate risk (substitute your verified value)
hubspot objects search --type subscriptions \
  --filter "hs_subscription_status=past_due" \
  --properties hs_recurring_billing_total,hs_subscription_status

# Map an at-risk subscription to its contact for outreach
hubspot associations list --from subscriptions:<sub_id> --to contacts --format jsonl

3 — フォローアップタスクまたはチェックインノートを作成する

アクティビティの作成は sales-execution にあります（完全なプロパティテーブル、ノート + ミーティングのフロー）。1 つのアンカー例 — 関連付けられていないタスクは CRM UI では表示されないため、必ず関連付けてください:

task_id=$(hubspot objects create --type tasks \
  --property hs_task_subject="Q1 retention check-in" \
  --property hs_task_priority=HIGH --property hs_task_status=NOT_STARTED \
  --property hs_task_type=CALL --property hs_timestamp=$(date +%s)000 \
  --format json | jq -r '.id')
hubspot associations create --from tasks:$task_id --to contacts:<contact_id>

4 — コホート向けの一括タスク作成

検索を jq を通して 1 回の objects create 呼び出しにパイプし、その後に関連付けます。objects create は Additive です — ダイジェストのゲートは一切ありません — そのため --dry-run は単なるプレビューであり、それを外すことで実行します（ダイジェスト／確認は不要）。ダイジェストのフローは、bulk-operations/SKILL.md にある不可逆的な書き込みにのみ適用されます。

DUE_MS=$(( ($(date +%s) + 2*86400) * 1000 ))   # due in 2 days

# 1. Capture the cohort (same file feeds both create + associate)
hubspot objects search --type contacts \
  --filter "lifecyclestage=customer AND notes_last_contacted<$CUTOFF" \
  --properties firstname > /tmp/inactive.jsonl

# 2. Build task payloads — one per contact
jq -c --arg due "$DUE_MS" '{
  contact_id: .id,
  properties: {
    hs_task_subject: ("Re-engage: " + (.properties.firstname // "customer")),
    hs_task_priority: "HIGH", hs_task_status: "NOT_STARTED",
    hs_task_type: "CALL", hs_timestamp: $due
  }
}' /tmp/inactive.jsonl > /tmp/task_payloads.jsonl

# 3. Dry-run, then create (drop contact_id before piping)
jq -c '{properties}' /tmp/task_payloads.jsonl | hubspot objects create --type tasks --dry-run | head
jq -c '{properties}' /tmp/task_payloads.jsonl | hubspot objects create --type tasks > /tmp/created.jsonl

# 4. Associate each new task to its contact — one piped call (associations create batches 100 pairs/API call; paste preserves order)
paste <(jq -r '.id' /tmp/created.jsonl) <(jq -r '.contact_id' /tmp/task_payloads.jsonl) \
  | jq -cR 'split("\t") | {from:("tasks:" + .[0]), to:("contacts:" + .[1])}' \
  | hubspot associations create

検索に 1 回、作成に 1 回、すべての関連付けに 1 回の CLI 呼び出し — レコードごとの xargs -I{} は不要です。objects create の出力順序の保証（stdin の 1 行につき 1 件の結果を、順番どおりに — bulk-operations の「Output shape」を参照）が、paste を正しく機能させます。

既知のギャップ

• ネイティブのチャーンスコア／ヘルススコアのプロパティはありません — カスタムプロパティで追跡してください。
• hubspot segments は再エンゲージメントコホート向けの CRM リストを提供します — segments members-list はリストのメンバーを取得し、segments create / update-filters はリスクのあるオーディエンスを再利用可能なリストとして保存します。再エンゲージメントの登録は、hubspot workflows create / update によるワークフローとして構築できます（workflow-automation/SKILL.md を参照）。
• hubspot sequences は Sales Hub のシーケンスを読み取ります（読み取り専用）: sequences enrollments <contact_id> を使用して、リスクのある顧客がこれまでに営業シーケンスを通じてエンゲージされたことがあるかを確認します。シーケンスは製品 API（Sales Hub Professional 以上、automation.sequences.read スコープ）であり、CRM オブジェクトタイプではありません — CLI はシーケンスを作成したり、コンタクトを登録したりすることはできません。このリストは時間とともに増えるため、API が存在しないと決めつけずに hubspot --help / CHANGELOG.md を再確認してください。
• hubspot associations create は stdin の JSONL をバッチ処理します（API 呼び出しあたり最大 100 ペア）— ループするのではなく、ペアを 1 回の呼び出しでパイプしてください。