> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aftersell.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 在 Stay AI 中使用订阅升级

> 在 Aftersell 中连接 Stay AI 并设置订阅升级的分步指南，包括 Stay AI 在预付计划、取消和货币方面的特有限制。

本页涵盖将 **Stay AI** 与订阅升级配合使用的所有特定内容，包括其独有的限制。有关订阅升级工作原理的完整概览，请参阅[订阅升级](/zh/aftersell/subscription-upgrades)。

<div id="supported-features">
  ## 支持的功能
</div>

Stay AI 支持所有订阅升级类型：

* 更改配送或计费频率（应用于整个订阅）
* 替换为其他产品
* 两者兼有 — 更改频率并替换产品
* 向订阅添加另一个可订阅商品（参阅[添加商品](/zh/aftersell/subscription-upgrades-add-item)）。如果客户已订阅该产品，Stay 会增加其数量，而不是添加新的行项目（这有一个价格匹配条件 — 参阅下方的限制）。
* 后付（按次配送付款）频率，包括将后付订阅转到预先付款计划（需满足下方的条件）

支持产品替换，**但不能替换为仅以预先付款计划销售的产品** — 参阅下方的预付限制。

<div id="moving-a-subscription-onto-a-pay-upfront-plan">
  ### 将订阅转到预先付款计划
</div>

支持将后付订阅切换为预先付款（预付）计划，但需满足两个条件：

* \*\*预先付款计划必须已存在于 Stay AI 中并已分配给该产品。\*\*Aftersell 无法创建此类计划；优惠只允许你从已在 Stay AI 中设置的计划中进行选择。
* **该转换会创建一个新订阅并取消旧订阅。**Stay 通过在预先付款计划上创建新订阅并取消原订阅来完成此变更，因此订阅会获得一个**新的引用**。按引用跟踪订阅的仓库、3PL 或报表工具需要重新同步。请参阅[履约与 3PL 映射](/zh/aftersell/subscription-upgrades-fulfillment)。

<div id="stay-ai-specific-limitations">
  ## Stay AI 特有的限制
</div>

* \*\*预付（预先付款）订阅无法修改。\*\*无论升级类型如何，Stay 都不允许对客户已预先付款的订阅进行任何更改。如果使用预付计划的客户接受了升级优惠，该升级会被取消并退款，订阅保持不变。出于同样的原因，你也无法将订阅替换为仅以预先付款计划销售的产品。
* **每个账户只能有一个应用接收取消信息。**Stay 只会向**每个账户的一个应用**发送取消更新。如果其他应用或集成在 Aftersell 之前注册了 Stay 的取消 webhook，Aftersell 将无法收到这些更新，[已取消订阅图表](/zh/aftersell/analytics_metrics_reference#subscriptions-cancelled-chart)也不会反映 Stay 的取消情况。你连接的 API 密钥必须包含 **Webhooks** 权限（见下文），取消跟踪才能正常工作。
* \*\*频率变更会应用于整个订阅。\*\*Stay 中每个订阅只有一个计划周期，因此更改配送频率会影响订阅上的所有产品。当订阅包含两个或更多产品时，你必须在优惠上启用 **Keep on existing subscription**；否则频率升级会被拒绝，购物者会获得退款。这仅适用于频率变更 — 产品替换和附加商品不受影响，无需此设置即可正常工作。
* \*\*为客户已订阅的产品增加数量需要价格匹配。\*\*当附加商品是客户已拥有的产品时，Stay 会增加其数量而不是添加新的行项目 — 但前提是优惠价格与客户当前为该产品支付的价格一致。如果价格不同（例如附加商品提供 20% 折扣，而客户的计划为 10% 折扣），升级会被拒绝，订阅保持不变。请为附加商品设置与客户计划相同的折扣，或提供其他产品（其他产品不受影响）。
* \*\*货币必须与你商店的定价一致。\*\*如果客户的订阅以你商店未定价的货币计费，升级会被拒绝。
* \*\*无法区分同一订单产生的重复订阅。\*\*如果同一订单创建了两个都包含优惠产品的 Stay 订阅，Aftersell 无法判断客户指的是哪一个，因此会拒绝升级，而不是将其应用到错误的合约上。
* \*\*速率限制会限制吞吐量。\*\*Stay 允许每个账户每分钟 60 次请求。一次升级需要四到六次请求，因此在高峰期，一个商店每分钟最多可处理约 10 到 15 次升级。

<div id="generating-your-stay-ai-api-key">
  ## 生成你的 Stay AI API 密钥
</div>

1. 在你的 Stay AI 控制台中，进入 **Account → API tokens → Add API key**。
2. 创建密钥时，选择 **All permissions**。Aftersell 需要访问 **Subscriptions**、**Orders**、**Selling Plan Groups** 和 **Webhooks**。Webhooks 权限让 Aftersell 能够获知取消情况。
3. 复制密钥并妥善保存。请像对待密码一样对待它。

更多详情请参阅 [Stay AI 的 API 身份验证文档](https://docs.stay.ai/reference/authentication)。

<div id="connecting-stay-ai-in-the-setup-wizard">
  ## 在设置向导中连接 Stay AI
</div>

当你进入订阅升级向导的**第 1 步：Connect provider** 时：

1. 在 **Subscription provider** 下拉菜单中选择 **Stay AI**。
2. 将你的 API 密钥粘贴到 **API key** 字段中。
3. 点击 **Test API key**。Aftersell 会验证密钥，检查它能否通过身份验证以及是否属于你的商店。
4. 测试通过（绿色对勾）后，点击 **Continue** 进入第 2 步。

测试结果会显示两种状态之一：

* \*\*绿色对勾 — "API key verified"。\*\*密钥通过了身份验证且属于你的商店。**Continue** 现已启用。如果密钥缺少 **Webhooks** 权限，测试仍会通过，但会警告订阅取消将不会被记录 — 如果你需要取消跟踪，请在 Stay AI 中使用 **All permissions** 重新创建密钥。
* \*\*红色取消图标。\*\*检查未能顺利通过。请阅读图标旁边的消息：要么密钥被拒绝，要么 Aftersell 无法完成检查（"Could not verify the API key. Please try again."），这属于调用失败而非密钥无效 — 这种情况下重新测试即可。

无法验证的结果看起来与被拒绝完全一样，因此请以消息内容而非图标为准。在检查结果变为绿色之前，**Continue** 保持禁用状态；编辑提供商或密钥会清除之前的结果。

<div id="verifying-an-upgrade-in-stay-ai">
  ## 在 Stay AI 中验证升级
</div>

下测试订单并接受升级优惠后：

进入 Stay AI 控制台的 **Subscriptions**，找到该客户的订阅。计费频率、产品或下次扣款日期应已反映此变更。

变更本身在 Aftersell 处理接受操作后会立即应用，但 Stay 接收全新订单的速度可能较慢：升级通常会在几分钟内生效，最慢的情况下可能需要 24 小时。如果变更尚未出现，请稍等一段时间，再判断是否失败。

<div id="if-an-upgrade-cant-be-applied">
  ## 如果升级无法应用
</div>

Stay AI 升级在设计上是安全的 — 购物者绝不会为未发生的升级付费：

* \*\*失败的升级会自动重试。\*\*如果对 Stay AI 的调用失败，Aftersell 会在后台工作流中重试。
* \*\*如果仍无法应用，购物者会获得退款。\*\*订阅升级只会在 Shopify 订单上收取一个小额的占位行项目费用（不是购物者保留的产品），因此当升级无法完成时，Aftersell 会退还该费用。
* **任何无法确认的情况都会被标记以供人工审核**，而不是凭猜测处理，因此购物者绝不会为未发生的升级付费。

有关完整的重试和对账机制（各提供商通用），请参阅[订阅升级的工作原理](/zh/aftersell/subscription-upgrades#how-subscription-upgrades-work)。

<div id="troubleshooting-stay-ai-specific-issues">
  ## 排查 Stay AI 特有的问题
</div>

**升级已被接受，但订阅未被修改**

最常见的原因是：

* 客户使用的是\*\*预付（预先付款）\*\*计划。Stay 不允许修改预付合约，因此升级会被取消并退款。这是预期行为。
* 订阅以**你商店未定价的货币**计费，因此升级被拒绝。
* 订阅包含**两个或更多产品**，而你在未启用 **Keep on existing subscription** 的情况下更改了频率。
* 同一订单创建了**两个都包含优惠产品的 Stay 订阅**，因此 Aftersell 无法判断应升级哪一个。
* 你的 API 密钥来自其他商店，或缺少必需的权限（**Subscriptions**、**Orders** 或 **Selling Plan Groups**）。请在 Stay AI 中重新创建或重新选择密钥，前往**第 1 步：Connect provider**，然后重新测试。
* 漏斗中符合条件的产品与客户实际订阅的产品不匹配。

Aftersell 会在后台工作流中自动重试失败的提供商调用。如果所有重试均失败，请联系支持团队，并提供你的商店 URL、Shopify 订单 ID、客户邮箱、升级被接受的大致时间以及你使用的提供商。

**Stay 的取消情况未显示在分析中**

Stay 只会向每个账户的一个应用发送取消更新。如果其他应用在 Aftersell 之前注册了 Stay 的取消 webhook，Aftersell 将无法收到这些更新。请确认没有其他集成占用 Stay 的取消 webhook，并确保所连接的 API 密钥包含 **Webhooks** 权限。

***

← 返回[订阅升级概览](/zh/aftersell/subscription-upgrades) · [设置与配置](/zh/aftersell/subscription-upgrades-setup) · [什么是集成？](/zh/aftersell/subscription-upgrades-integrations)