> ## 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.

# 订阅升级故障排查

> 常见订阅升级问题的解决方法，包括升级失败警报、提供商连接问题和空的销售计划下拉菜单。

最常见订阅升级问题的解决方法。如果尝试这些方法后仍然无法解决，请联系支持团队，并提供[测试与验证](/zh/aftersell/subscription-upgrades-testing#when-something-looks-wrong)中列出的详细信息。

<div id="monitoring-upgrade-failures">
  ## 监控升级失败
</div>

Aftersell 会在滚动的 7 天窗口内监控最终性的升级失败。如果失败数量超过警报阈值，你的首页会出现一个**警告横幅**，说明有多少次升级失败以及跨越了多少天。同一警报也会出现在[首页](/zh/aftersell/home/needs-attention)的 **Needs attention** 面板中。

该警报包含一个 **Review orders** 按钮，可直接带你进入按订阅升级问题筛选的订单浏览器，让你查看受影响的订单以及每次失败的具体原因。一旦滚动窗口内的失败数量降到阈值以下，警报会自动清除。如果你看到此警报，请打开订单浏览器，查看每个受影响订单上显示的原因，然后参考下方相应的故障排查步骤。

<AccordionGroup>
  <Accordion title="我无法通过第 1 步：Connect provider">
    **Subscription Upgrade** 模板永远不会被隐藏 — 无论你的提供商设置如何，它始终列在 **Add Funnel** 下。阻碍你的是第 1 步的连接检查：在 **Test API key** 返回带绿色对勾的 **API key verified** 之前，**Continue** 保持禁用状态。

    两种不同的结果会显示同样的红色取消图标，因此请阅读图标旁边的消息：

    * \*\*你的提供商拒绝了该密钥。\*\*令牌缺少必需的权限范围或已被吊销，消息会指明具体问题。请在提供商控制台中签发一个具有[设置与配置](/zh/aftersell/subscription-upgrades-setup)中所列权限范围的新令牌，粘贴进来并重新测试。
    * **Aftersell 无法连接到你的提供商** — "Could not verify the API key. Please try again."。令牌本身不一定有问题；是调用本身失败了。再次点击 **Test API key** 即可。

    编辑提供商或令牌会清除之前的结果，因此任何更改后都要重新测试。
  </Accordion>

  <Accordion title="我的客户在订单中看到了预期之外的产品">
    这是预期行为。该产品是优惠产品，即作为已接受升级的记录添加到 Shopify 订单中的占位行项目。为减少困惑，可以在 Shopify Admin 中将优惠产品重命名为清晰的名称，并添加说明其含义的描述。参阅[客户看到什么](/zh/aftersell/subscription-upgrades#what-the-customer-sees)。
  </Accordion>

  <Accordion title="升级已被接受，但订阅未被修改">
    Shopify 的变更集和提供商 API 调用是相互独立的。如果优惠产品已添加到订单中但订阅没有变化，最常见的原因是：

    * 你的提供商 API 令牌已过期或缺少必需权限。对于 Recharge，令牌必须具有 `read_orders`、`read_subscriptions`、`write_subscriptions` 和 `read_plans`。请前往**第 1 步：Connect provider**，重新测试你的密钥，并查看错误消息中指明的缺失权限范围。
    * 漏斗中符合条件的产品与客户实际订阅的产品不匹配。
    * 对于 Loop，配置的频率在你的 Loop 控制台中不存在对应的目标销售计划。
    * 重试工作流可能仍在按计划执行：调用失败后，它会在 +1 小时后重试，然后在 +24 小时后再次重试。这对每个提供商都一样 — 包括 Loop，其升级调用是同步的，成功后会立即显示在控制台中。

    Aftersell 会在后台工作流中自动重试失败的提供商调用。工作流在重新运行之前会检查提供商的当前状态，因此成功但缓慢的升级不会被应用两次。

    如果重放无法解决失败原因，工作流会**退还费用**（当没有任何提供商变更成功且被扣款的行项目是占位产品时），或将升级标记为**人工对账**，同时保持订单不变。全新订阅和套盒升级绝不会自动退款，因为购物者收到的是真实产品。请联系支持团队，并提供[测试与验证](/zh/aftersell/subscription-upgrades-testing#when-something-looks-wrong)中列出的详细信息。
  </Accordion>

  <Accordion title="销售计划下拉菜单为空">
    "Use an existing selling plan" 选项直接从 Recharge、Skio 或 Loop 拉取计划。如果下拉菜单为空：

    * 确认你的提供商控制台中已配置销售计划。
    * 确保你的 API 令牌对 Plans 具有读取权限（Recharge：`read_plans` 权限范围）或相应的权限范围（Skio、Loop）。
    * 返回**第 1 步：Connect provider**，重新测试你的 API 密钥，然后继续。
  </Accordion>

  <Accordion title="我使用 Loop，但没有计费频率字段">
    这是预期行为。在 Loop 上，**Billing frequency** 字段完全不显示 — 只显示 **Delivery frequency**，并附有说明 "Loop syncs billing to delivery — customers are charged on each renewal"。你设置的配送频率同时也是计费频率。

    这也是 Loop 不支持预付订阅（计费频率长于配送频率）的原因：该集成会直接拒绝它们，而不是提供一个你无法使用的字段。其他提供商会显示两个字段。
  </Accordion>

  <Accordion title="订单浏览器显示 Subscription conflict 标记">
    优惠产品是仅限订阅的 — 要么产品本身如此，要么其所有款式都如此 — 而客户的 checkout 中已包含一个订阅。Shopify 不允许同一订单上有第二个订阅，因此该优惠被跳过。

    订单详情面板会明确说明属于哪种情况："The customer's checkout already has a subscription, and the offer product is subscription-only"，或 "All variants of the offer product are subscriptions, and the customer's checkout already has one."。两种情况的解决方式相同 — 编辑优惠的产品选择，换成支持一次性购买的产品，或在**第 4 步：Offer product** 中使用 **Create new** 选项生成一个占位产品。
  </Accordion>

  <Accordion title="我的升级优惠展示给了非订阅者客户">
    * 检查是否启用了 **Show this funnel for all customers**。它会覆盖所有其他触发条件。
    * 检查 **Variant on subscription** 触发条件。它仅在订单包含所选产品之一且是*以订阅形式购买*时才展示漏斗。在包含订阅升级优惠的漏斗上，向导拥有此触发条件的控制权，并使其与被升级的产品保持同步，因此它是只读的 — 面板显示 "Managed by this funnel's subscription upgrade offer."。如果它定向的产品不对，请修正升级优惠的触发产品，而不是触发条件本身。
    * 检查漏斗优先级。触发条件更宽泛的高优先级漏斗可能会先触发。

    <Warning>
      不要试图用单独的产品触发条件加订阅触发条件来复现此功能。这种组合正是 **Variant on subscription** 所取代的：两者独立匹配，因此一个包含作为一次性购买的触发产品*和*一个不相关订阅商品的订单会同时满足两者，触发漏斗，然后升级在下游失败。将产品与订阅状态一起匹配的单一触发条件才是受支持的设置。
    </Warning>
  </Accordion>
</AccordionGroup>