用途:在 HubSpot 中完成从报价到收入的流程操作,包括创建产品、组装报价、关联交易、追踪发票与订阅。
主要能力:
- 创建产品:使用 hubspot objects create --type products,可设置 name、price、hs_sku 等属性;定期产品需设置 recurringbillingfrequency。
- 组装报价:通过 JSONL 管道批量创建行项目(line_items),捕获其 ID 并关联到新建报价;再用 hubspot associations create 将报价关联到交易。注意 objects create 每行输入产出一行结果,顺序一致。优惠使用 discount 字段(可写百分比,10 表示 10% 折扣),hs_total_discount 由 HubSpot 计算,只读。
- 报价状态:CLI 创建的报价始终为 DRAFT,可用 objects update 将 hs_status 更新为 APPROVAL_NOT_NEEDED 等值,更新不可逆,需先 --dry-run,再带 digest 与 --confirm <quote_id> 执行。
- 追踪发票:用 hubspot objects search --type invoices 按 hs_invoice_status、日期等筛选,可查未结、逾期、近 30 天开票等。
- 追踪订阅:同样用 objects search --type subscriptions 按 hs_subscription_status 筛选,可汇总活跃订阅的 MRR。
必要用法:
- 先阅读 bulk-operations/SKILL.md,了解 JSONL 管道、批量读取、分页与破坏性操作的 dry-run/digest/confirm 流程。
- 对象类型为复数:products、line_items、quotes、invoices、subscriptions。
- 不要硬编码属性表,可用 hubspot properties list --type <type> 获取。
- 写入任何枚举值前,先用 hubspot properties options-list --type <type> <property> | jq -r '.value' 验证。
- hubspot <command> --help 是权威来源。
适用场景:需要批量管理 HubSpot 产品目录、报价、发票与订阅收入流程,并通过脚本或管道自动化操作时。
限制:
- invoices、subscriptions、orders、carts、payments 在 hubspot objects types 中 objectTypeId 为空,需令牌具备对应读权限(如 invoices-read、subscriptions-read),否则返回 403。
- CLI 创建的报价始终为 DRAFT;审批路由、分享链接、PDF 生成和从零创建发票通常需要 HubSpot UI。
- objects delete 在用户 OAuth(hubspot auth login,需对象写权限)和服务密钥(export HUBSPOT_ACCESS_TOKEN=<token>)下均可工作,但 --gdpr 永久清除仅支持服务密钥,GDPR 端点不接受用户 OAuth 令牌。
- hs_total_discount 为只读,应设置 discount 百分比。
- 订阅状态筛选注意大小写,先验证枚举值。
其他细节(如分享链接、PDF、审批路由的具体步骤)暂未提供。