stigg-subscriptions

Stigg 订阅 — 生命周期操作

本技能涵盖日常订阅操作：开通、预览、更新、取消、试用、多订阅产品，以及计划版本迁移（发布后将现有订阅从计划 v1 迁移到计划 v2）。

开始之前

根据总览 stigg 技能：先搜索。 开通选项、计费周期行为和试用转付费语义都可能变化。编写内容前，请先打开相关 SDK / REST 页面（Mintlify Stigg 文档 MCP）。

操作一览

操作	用途	参考
开通	为客户创建计划订阅（+ 添加项、试用、账单详情）	references/provisioning.md
预览	在开通前计算假设订阅的价格	见下文
更新	更改有效订阅的计划 / 添加项 / 周期 / 数量 / 支出 / 优惠券 / 试用	references/updates.md
取消	立即取消订阅、在周期结束时取消，或在指定日期取消	见下文
试用	开始试用、转为付费、处理到期	references/trials.md
多个有效订阅	一个客户拥有多个订阅，按 resourceId 进行范围限定	见下文
计划版本迁移	将现有订阅从计划 v1 迁移到计划 v2（发布后）	references/plan-version-migration.md

开通订阅

最简后端调用

const sub = await stigg.provisionSubscription({
  customerId: 'customer-123',
  planId: 'plan-pro',
  billingCountryCode: 'US',           // required for paid plans w/ price localization
});

开通时可设置以下内容（完整列表请参见 references/provisioning.md）：

• 资源 ID — 产品允许多个有效订阅时必填。
• 计费周期 — 付费计划适用，例如按月 / 按年等。
• 计划配置 — 预先承诺费用和可变权益的单位数量；价格覆盖。
• 添加项 — 与计划兼容的添加项列表（及其数量）。
• 订阅开始日期 — Immediately（默认）/ EndOfCurrentBillingPeriod（已有有效付费订阅时）/ SpecificDate（过去日期 = 追溯生效，不立即收费；未来日期 = 在该日期激活）。
• 免费试用 — 适用于付费计划 / 自定义计划。
• 支出管理 — minimumSpend、maximumSpend。
• 折扣 — 应用优惠券（适用于整个目录，或针对特定订阅临时创建）。
• 付款方式 — automaticallyUsePaymentMethodOnFile / 生成发票 / 不通过 Stigg 付款。
• 计费周期锚点 — UNCHANGED（默认）/ NOW。
• 按比例计费 — ProrateNow / ProrateOnNextInvoice / NoProration。

权益取优规则： 当客户的有效权益来自多个来源时 — 有效订阅、添加项、试用、促销权益、额外产品订阅 — Stigg 会从所有来源中选取最慷慨的值。“试用与付费”的情况只是这一规则的一个例子；只要来源重叠，该规则就适用。

预览订阅

开通前，预览即时发票和周期性发票：

const preview = await stigg.previewSubscription({
  customerId: 'customer-123',
  planId: 'plan-pro',
  billingPeriod: 'MONTHLY',
  addons: [{ addonId: 'addon-seats', quantity: 10 }],
  couponId: 'SAVE20',                          // optional
  subscriptionId: 'sub-789',                   // optional — preview an UPDATE to an existing sub
});

Node SDK / GraphQL 会返回 immediateInvoice 和 recurringInvoice，每个金额都是 { amount, currency } Money 对象（subtotal 为小写）。直接调用 REST 的用户会看到更扁平的 DTO，其中金额是标量，字段名为 subTotal（T 大写）。金额以货币的完整单位表示，而非分 — 49 表示 $49.00（Stripe 采用相反约定，因此熟悉 Stripe 的开发者容易在这里出错）。完整结构和 previewSubscription 的使用场景请参见 references/provisioning.md。

更新订阅

重要：updateSubscription（GraphQL mutation）不支持更改套餐。如需更改订阅套餐，请再次调用 provisionSubscription——Stigg 会通过正确的机制处理（根据套餐类型转换，进行原地更新或替换；请参见下方的迁移矩阵）。

// Update — addons, billing period, billable features, price overrides
await stigg.updateSubscription({
  subscriptionId: 'sub-123',
  addons: [{ addonId: 'addon-seats', quantity: 10 }],
  billingPeriod: 'ANNUAL',
});

// Change plan — re-provision (NOT updateSubscription)
await stigg.provisionSubscription({
  customerId: 'customer-123',
  planId: 'plan-pro',          // new plan
  // ...other provisioning fields
});

updateSubscription 直接支持的内容（根据 GraphQL mutation 接口）：

• 计费周期（付费套餐，例如 MONTHLY → ANNUAL）。
• 附加项（替换现有项——传入新的完整列表）。
• 计费功能（预付承诺数量、按单位计费的数量）。
• 价格覆盖。

Stigg 应用 UI 提供的其他更新流程（延长 / 缩短试用期、更改支出限额、应用优惠券、重置计费周期锚点、对变更进行按比例计费）通过**单独的 SDK 方法或再次调用 provisionSubscription**实现——请搜索文档以查找具体操作。

**计划更新会替换，而非排队：**新的更新会覆盖任何待处理的计划更新，并立即生效（Stigg 应用 UI 文档中有说明；SDK 的行为通常一致——请查阅所用 SDK 的文档确认）。

详细流程和模式：references/updates.md。

取消订阅

通过 @stigg/node-server-sdk（该 SDK 会转换为 cancelSubscription GraphQL mutation）：

await stigg.cancelSubscription({
  subscriptionId: 'sub-789',                              // Node SDK uses subscriptionId
  subscriptionCancellationTime: 'END_OF_BILLING_PERIOD',  // or 'IMMEDIATE' / 'SPECIFIC_DATE'
  // endDate: '2026-06-01T00:00:00Z',                     // required when SPECIFIC_DATE
  // subscriptionCancellationAction: 'DEFAULT',           // or 'REVOKE_ENTITLEMENTS'
  // prorate: false,
});

**字段名称说明：**Node SDK 使用 subscriptionId。Python / Go / Ruby / Java / .NET SDK 和原始 GraphQL mutation 使用 subscriptionRefId。直接调用 REST 时，ID 位于 URL 路径中。

subscriptionCancellationTime：

值	行为
IMMEDIATE	立即取消。
END_OF_BILLING_PERIOD	在当前计费周期结束时取消。大多数产品的默认值。不适用于自定义定价套餐或试用订阅。
SPECIFIC_DATE	在 endDate 指定的日期取消。不适用于试用期。

subscriptionCancellationAction：

值	行为
DEFAULT	产品的默认取消行为（根据产品策略，撤销访问权限或降级至免费套餐）。
REVOKE_ENTITLEMENTS	取消时立即撤销所有权益。

取消后的状态：CANCELED（已结束）或 CANCELLATION_SCHEDULED（待处理）。

直接调用 REST 的用户（通过 curl 调用 https://api.stigg.io/api/v1）：未加前缀的 REST 字段名称为 cancellationTime、cancellationAction、endDate、prorate。枚举值相同。

试用

付费套餐和自定义套餐均可试用。套餐定义默认试用设置；创建订阅时可覆盖该设置。

• 创建试用订阅——在创建时传入试用配置。
• 将试用转换为付费订阅——在现有试用订阅上创建付费订阅；Stigg 会在试用结束时启动付费套餐。
• 试用到期但未转换——触发 trial.expired 事件；从你的应用触发召回流程。
• 自助流程中，每位客户针对每种产品只能试用一次（管理员可覆盖此限制）。
• 已付费的客户不符合再次自助免费试用的条件。

详细机制和示例（应用内升级、带附加项的试用）：references/trials.md。

每位客户的多个活跃订阅

对于多租户产品（工作区／项目／应用），单个客户可以持有多个订阅，并按 resourceId 区分范围：

const sub = await stigg.provisionSubscription({
  customerId: 'customer-123',
  resourceId: 'workspace-abc',
  planId: 'plan-team',
});

启用后（这是产品级设置，在创建产品时固定）：

• 在每次相关调用中传入 resourceId——开通、更新、权益检查、用量报告、付费墙组件。
• 客户可以在每个工作区分别订阅不同计划，并使用同一种付款方式付费。
• **试用与付费：**每个 (customer, resource) 对最多只能有一个活跃试用订阅，且最多只能有一个活跃的非试用订阅。
• 可以与单实例产品结合使用（将另一个产品设为“单个活跃订阅”），以建模“账户 + 子账户”／“平台 + 应用实例”，例如 Webflow 的账户 + 每个站点模式。

**产品有任何订阅后，就不能再切换是否启用多活跃订阅。**请在创建产品时决定。

计划版本迁移（目录 v1 → v2）

重新发布计划时，现有订阅会继续使用旧版本，除非进行迁移。这是常规的持续性操作。

目录端的发布流程（草稿、版本策略、触发保留旧版本的条件）见 stigg-pricing-modeling/references/plans.md。本节介绍的是订阅端的迁移机制。

根据计划类型的转换，Stigg 会自动选择以下两种迁移机制之一：

路径	机制	原因
免费 → 付费	开通新订阅	付费计划需要可计费指标的值。
免费 → 自定义	开通新订阅	自定义计划的可变权益需要设置值。
付费 → 免费	迁移到最新版本	原位迁移。
付费 → 自定义	迁移到最新版本	原位迁移；现有外部计费系统中的订阅不会取消——只会移除 Stigg 端的元数据。
自定义 → 付费	开通新订阅	付费计划需要可计费指标的值。
自定义 → 免费	迁移到最新版本	原位迁移。

触发迁移：

• UI：打开订阅，选择 ⋮ → 迁移到最新版本 → 选择立即或在当前周期结束时。
• **编程方式：**调用迁移订阅 mutation／SDK 方法。可用于渐进式推出。

如果选择立即迁移，且客户当前价格与最新发布的价格不同，Stigg 会自动收取或抵扣按比例计算的金额。

详细迁移参考：references/plan-version-migration.md。

何时不应使用此技能

• 对功能／计划／附加项进行建模 → stigg-pricing-modeling。
• 运行时权益检查／用量报告 → stigg-entitlements。
• 定价模型的策略建议 → stigg-pricing-expert。

常见错误

错误	修正方法
多活跃订阅产品漏传 resourceId	每次调用（开通／更新／权益／用量／组件）都需要传入。
把计划更新当作队列	新更新会替换已安排的更新。如果需要队列，请在应用中自行建模。
产品策略规定在周期结束时取消，却立即取消	使用产品默认设置；只有确实需要立即取消时才选择立即取消。
试图在周期结束时取消自定义定价计划	取消弹窗不支持此操作。请指定日期或与计费团队协调。
客户已付费，却仍允许其自行开通试用	不符合条件。需要管理员覆盖此限制。请在应用中显示正确的 CTA。
收费前跳过 previewSubscription	客户希望先看到应付金额。请先预览，再开通订阅。
重大升级时未设置 billingCycleAnchor: NOW	客户的账单周期会逐渐偏移。如果变更应开启全新周期，请明确重置。