customer-retention

资源

文件	适用场景
resources/customer-health-signals.md	流失信号筛选指南 — --filter 表达式适用于 notes_last_contacted、hs_last_sales_activity_date、hs_email_optout、过期工单、订阅状态。

前置条件

先阅读 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]。它会将各属性的来源历史展平为每次变更一行。

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（完整属性表、备注和会议流程）。以下是一个基本示例 — 未关联的任务在 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，再调用一次 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

搜索调用一次、创建调用一次，所有关联再调用一次 — 不要对每条记录使用 xargs -I{}。objects create 的输出顺序保证（每行 stdin 对应一个结果，且顺序一致 — 参见 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> 查看有风险的客户是否曾通过销售序列进行互动。Sequences 是产品 API（Sales Hub Professional+，需要 automation.sequences.read 权限范围），不是 CRM 对象类型 — CLI 无法创建序列或让联系人加入序列。此列表会随时间增长；请重新检查 hubspot --help／CHANGELOG.md，不要直接假定某个 API 不存在。
• hubspot associations create 可批量接收 stdin JSONL（每次 API 调用最多 100 对）— 请一次性通过管道传入所有对象对，而不要循环处理。