quote-to-cash

资源

文件	使用时机
resources/q2c-essentials.md	六字段速查表、关联方向，以及发票/订阅/订单/购物车的门户注意事项。

基础知识

首先阅读 bulk-operations/SKILL.md——JSONL 管道传输、批量读取、分页，以及破坏性操作的 dry-run/digest/confirm 流程都在其中。数据重塑方法（读取 → 写入载荷）见 bulk-operations/resources/json-patterns.md。

hubspot <command> --help 是权威信息来源。对象类型使用复数形式（products、line_items、quotes、invoices、subscriptions）。切勿硬编码属性表——只需调用一次 hubspot properties list --type <type> 即可获取。写入任何枚举值前，请先用 hubspot properties options-list --type <type> <property> | jq -r '.value' 验证 Agent 即将写入的值。

门户注意事项：在 hubspot objects types 中，invoices、subscriptions、orders、carts 的 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 的每一行输出一条结果。这意味着你可以通过三段管道创建行项目、提取其 ID，并将它们关联到新报价单，无需逐条记录编写 shell 循环。

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 不可撤销——请先运行 dry-run，再使用摘要和 --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 登录或私有应用令牌缺少该作用域。
• 在产品/报价单/行项目上执行 objects delete，用户 OAuth（hubspot auth login，且需具有对象的写入作用域）和服务密钥（export HUBSPOT_ACCESS_TOKEN=<token>）均可使用；403 表示当前令牌缺少该写入作用域。例外是 --gdpr 永久清除操作，它需要服务密钥——GDPR 端点不接受用户 OAuth 令牌。批量删除产品目录记录前，请参阅 bulk-operations/SKILL.md 中的 dry-run → digest → confirm 流程。
• 报价单分享链接、PDF 生成、审批路由和从头创建发票只能通过 UI 操作——CLI 可以更新记录，但无法向客户发送报价单。
• 行项目上的 hs_total_discount 为只读属性——请设置 discount（百分比）替代。