使用 HubSpot CLI 管理产品目录、报价…

当需要通过 HubSpot CLI 从产品目录、报价行项目、交易关联一路追踪发票和订阅收入时，按这套流程操作。

适用场景

解决思路

1. 查阅 `resources/q2c-essentials.md`：获取六字段速查表、关联方向，以及 invoices/subscriptions/orders/carts 的门户注意事项。
2. 先阅读 `bulk-operations/SKILL.md`：掌握 JSONL 管道、批量读取、分页，以及破坏性操作的 dry-run/digest/confirm 流程；读→写 payload 的改造配方见 `bulk-operations/resources/json-patterns.md`。
3. 以 `hubspot <command> --help` 为最终依据。
4. 对象类型用复数：`products`、`line_items`、`quotes`、`invoices`、`subscriptions`。不要硬编码属性表；用 `hubspot properties list --type <type>` 查询。
5. 写任何 enum 值前先验证：`hubspot properties get --type <type> --name <property>` 并读取 `options[].value`。
6. 门户注意：`invoices`、`subscriptions`、`orders`、`carts` 在 `hubspot objects types` 中 `objectTypeId` 为空；当 token 有匹配 scope（如 `invoices-read`、`subscriptions-read`）时可通过 `objects search`/`list` 使用，否则 403。CLI 创建的 quote 始终是 `DRAFT`；审批路由、分享链接、PDF 生成、发票创建通常需要 HubSpot UI。
7. 创建产品：`hubspot objects create --type products --property name="Enterprise License" --property price=12000 --property hs_sku=ENT-001`。
8. 对周期性计费产品设置 `recurringbillingfrequency`；先用 `hubspot properties get --type products --name recurringbillingfrequency --format json | jq -r '.options[].value'` 检查 API enum 值。
9. 批量导入产品目录：将每行 `{"properties":{...}}` 的 JSONL 管道传给 `hubspot objects create --type products --dry-run`。
10. 利用 `objects create` 对 stdin 的每一行按输入顺序输出一行结果，用三条管道创建 line items、捕获其 ID，并关联到新 quote，无需逐条 shell 循环。
11. 创建 line items：`items.jsonl` 每行包含 `{"name":..,"qty":..,"price":..,"product_id":..}`；用 `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`。
12. 创建 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')`。
13. 将所有新 line item 关联到 quote：`jq -r '.id' /tmp/lineitems.jsonl | jq -cR --arg q "$QUOTE_ID" '{from:("quotes:" + $q), to:("line_items:" + .)}' | hubspot associations create`。
14. 将 quote 关联到 deal：`hubspot associations create --from "deals:$DEAL_ID" --to "quotes:$QUOTE_ID"`。
15. 折扣处理：`discount` 是可写百分比（`10` 表示 10% off），`hs_total_discount` 由 HubSpot 计算，不要设置；在不拥有的门户中依赖它之前，用 `hubspot properties get --type line_items --name hs_total_discount` 查看 `modificationMetadata.readOnlyValue:true` 来验证。
16. 准备分享时，将 quote 从 `DRAFT` 提升：`hubspot objects update --type quotes <quote_id> --property hs_status=APPROVAL_NOT_NEEDED`。
17. 验证 `hs_status` enum 值：`hubspot properties get --type quotes --name hs_status --format json | jq -r '.options[].value'`。
18. 追踪发票：CLI 可读取发票数据并更新状态；创建通常需要 HubSpot Commerce + UI。按 `hs_invoice_status` 和日期过滤。
19. 查所有未结发票：`hubspot objects search --type invoices --filter "hs_invoice_status=OUTSTANDING" --properties hs_number,hs_amount_billed,hs_balance,hs_due_date`。
20. 查逾期发票（动态日期）：`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`。
21. 查最近 30 天开票的发票：`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`。
22. 验证发票状态 enum：`hubspot properties get --type invoices --name hs_invoice_status --format json | jq -r '.options[].value'`。
23. 追踪订阅：同样形状，按 `hs_subscription_status` 过滤；写过滤条件前验证 enum 值——不要硬编码 `ACTIVE`/`CANCELLED`/`PAST_DUE`。
24. 验证订阅状态 enum：`hubspot properties get --type subscriptions --name hs_subscription_status --format json | jq -r '.options[].value'`。
25. 过滤订阅（大小写敏感）：`hubspot objects search --type subscriptions --filter "hs_subscription_status=<value-from-above>" --properties hs_mrr,hs_arr,hs_subscription_status`。
26. 汇总活跃订阅 MRR：`hubspot objects search --type subscriptions --filter "hs_subscription_status=<active-value>" --format json | jq '[.data[].properties.hs_mrr | select(. != null) | tonumber] | add'`。
27. `invoices`、`subscriptions`、`orders`、`carts` 需要当前 token 具备匹配的读 scope；403 表示用户 OAuth 登录或 private-app token 缺少 scope。
28. 破坏性操作（对 products/quotes/line_items 执行 `objects delete`）通常需要 private-app token：`export HUBSPOT_ACCESS_TOKEN=<token>`；批量删除目录记录前按 `bulk-operations/SKILL.md` 执行 dry-run → digest → confirm。
29. Quote 分享链接、PDF 生成、审批路由、从零创建发票只能走 UI；CLI 可更新记录但不能向客户发送 quote。
30. `hs_total_discount` 在 line items 上是只读的——改为设置 `discount`（百分比）。

适用边界 · 注意事项

• 当没有 HubSpot CLI、private app/OAuth token 或所需 scope（如 `invoices-read`、`subscriptions-read`）时，不适用；403 表示缺少 scope。
• 当任务需要从零创建发票、生成报价分享链接/PDF、审批路由等 UI-only 能力时，不适用，应使用 HubSpot UI。
• 当未按 `bulk-operations/SKILL.md` 完成 dry-run → digest → confirm 时，不要执行批量删除 products/quotes/line_items。