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

# 为什么我的 checkout upsell 不显示？

> 完整梳理 checkout upsell 可能不显示的所有原因，包括设置、位置、触发器以及商品/优惠问题。

Checkout upsell 可能因多种不同原因而无法显示。请按顺序完成以下步骤以找出原因。

<Note>
  Checkout upsell 仅适用于 Shopify Plus 商家，因为 Shopify 的 Checkout Extensibility API 仅面向 Plus。如果你不在 Shopify Plus 套餐上，无论如何配置，checkout upsell 都不会显示。请参阅[为什么我看不到 checkout 标签页？](/zh/aftersell/why_cant_i_see_the_checkout_tab)
</Note>

<Tip>
  如果某个 upsell 未显示，客户的 checkout 体验不会受到影响 — 客户端不会出现任何问题。
</Tip>

***

<div id="where-to-start">
  ## 从哪里开始
</div>

大多数显示问题归结为以下四种情况之一：小组件未启用、应用区块未在 Shopify 中添加/保存、位置不匹配，或触发条件未满足。请先确认基础事项：

* 你使用的是 **Shopify Plus** 套餐
* 小组件已在 Aftersell Checkout 编辑器中**启用**（小组件设置右上角的 **Enable** 开关已打开）
* 应用区块已在 Shopify Checkout 编辑器中**添加并保存**
* 在 Shopify 中选择的位置与 Aftersell 中设置的位置**匹配**

如果以上都没问题但 upsell 仍不显示，请逐一排查下面的详细原因。

* [小组件未启用或未添加到 checkout](#widget-is-not-enabled-or-not-added-to-checkout)
* [Aftersell 与 Shopify 之间的位置不匹配](#placement-mismatch-between-aftersell-and-shopify)
* [触发条件未满足](#trigger-conditions-are-not-being-met)
* [存在商品或优惠问题](#there-is-a-product-or-offer-issue)
* [Shop Pay 小组件不显示](#shop-pay-widgets-not-showing)
* [在 Shopify 预览中测试](#testing-in-the-shopify-preview)
* [以上都不适用](#nothing-above-applies)

***

<div id="widget-is-not-enabled-or-not-added-to-checkout">
  ## 小组件未启用或未添加到 checkout
</div>

要让 checkout upsell 显示，必须同时满足两个条件：

1. 小组件必须在 Aftersell Checkout 编辑器中**启用**
2. 应用区块必须在 Shopify Checkout 编辑器中**添加并保存**

缺少任何一项，小组件都不会显示。

**在 Aftersell 中启用小组件：**

1. 前往 **Apps → Aftersell → Checkout**
2. 打开你想显示的 upsell 小组件
3. 确认小组件已开启 — 页眉中会显示 **Active** / **Inactive** 徽章旁的开关。（在早期版本的 Checkout 编辑器中，这是小组件卡片页眉中的 **Enable** / **Disable** 按钮对。）

**在 Shopify 中添加应用区块：**

1. 在 Shopify 后台前往 **Settings → Checkout**
2. 点击你的 checkout 配置文件旁的 **Customize**
3. 点击 **Add app block** 并选择 Aftersell upsell 小组件
4. 将它放置到你希望显示的位置
5. 点击 **Save** — 更改在保存之前不会生效

***

<div id="placement-mismatch-between-aftersell-and-shopify">
  ## Aftersell 与 Shopify 之间的位置不匹配
</div>

位置不匹配是 checkout upsell 无法显示的最常见原因之一。

Aftersell 支持多个位置（placement），因此你可以在同一个 checkout 页面上运行多个相同类型的小组件。每个位置对应 Shopify Checkout 编辑器中的一个**独立应用区块**，且在 Shopify 中选择的位置必须与 Aftersell 中配置的位置匹配。

Upsell Widget 应用区块的 **Placement** 下拉菜单提供八个值：**Default placement (Upsell Widget 1)**、**Additional placement 1 (Upsell Widget 2)**、**Additional placement 2 (Upsell Widget 3)**，以及五个页面小组件插槽 **page-upsell-001** 至 **page-upsell-005**。

如果位置不匹配，小组件将不会显示，或可能显示在错误的位置。

**修复位置不匹配：**

1. 在 Aftersell Checkout 编辑器中，打开该 upsell 小组件并记下所选的位置（例如 **Additional placement 1**）
2. 在 Shopify Checkout 编辑器中，移除该小组件的现有应用区块
3. 点击 **Add app block**，选择 Aftersell upsell 小组件，并选择与 Aftersell 中配置**相同的位置**
4. 保存更改

[进一步了解位置匹配 →](/zh/aftersell/how_to_configure_checkout_widgets#matching-placements-in-the-shopify-checkout-editor)

***

<div id="trigger-conditions-are-not-being-met">
  ## 触发条件未满足
</div>

如果你的 upsell 小组件配置了触发器，则只有当购物车满足这些条件时它才会显示。如果购物车不满足触发条件，小组件就不会显示 — 这是预期行为。

可用的触发器类型包括：

* \*\*特定商品/系列：\*\*所选商品、变体或系列在（或不在）购物车中
* \*\*特定商品的数量：\*\*例如某商品数量达到 2 件或以上
* \*\*商品标签/商品类型/变体名称：\*\*任一购物车商品匹配 Shopify 标签、商品类型或变体标题（不区分大小写）
* \*\*商品 metafield/变体 metafield：\*\*购物车中的商品或变体具有匹配的 metafield 值
* \*\*购物车小计：\*\*小计达到某个阈值（有关小计的计算方式，请参阅下面的说明）
* \*\*购物车数量：\*\*购物车中的商品总数
* \*\*购物车中的订阅：\*\*购物车中是否有订阅商品
* \*\*购物车属性：\*\*购物车级别的属性键/值匹配（对于其他应用设置的数据很有用）
* \*\*应用的折扣/折扣金额：\*\*应用了特定折扣码，或总折扣达到某个阈值
* \*\*收货国家/地区：\*\*客户的收货国家/地区（以及可选的省份）匹配
* \*\*客户语言：\*\*checkout 的语言匹配（例如，仅向法语 checkout 显示法语内容）
* \*\*客户标签：\*\*已登录客户拥有所需的标签
* \*\*设备类型：\*\*客户使用配置的设备（桌面端或移动端）

<Note>
  用于触发器评估的**购物车小计**不包括已接受的 upsell 添加的任何行项目（即带有 `__as_offer_id` 购物车属性标记的项目）。因此，接受一个 upsell 本身不会将小计推过控制另一个小组件的阈值。
</Note>

\*\*组合条件：\*\*当一个小组件有多个条件时，它们通过 **AND** 或 **OR** 连接（由你选择），并且条件可以嵌套成组以实现更复杂的逻辑。在 **AND** 连接下，必须满足每个条件 — 只要有一个条件不匹配，小组件就会被悄悄阻止显示。在 **OR** 连接下，任意一个匹配即可。请针对你的测试购物车逐一检查每个条件。

**排查触发器：**

1. 在 Aftersell Checkout 编辑器中打开该小组件并检查其触发条件
2. 暂时将触发器设置为 **Show for all customers**，以确认小组件本身正常工作，然后重新启用你的特定触发器
3. 确保至少有一个小组件在最低优先级使用 **Show for all customers** 触发器作为兜底，这样即使没有定向小组件匹配，也总会有优惠显示

[进一步了解 checkout 触发器 →](/zh/aftersell/checkout_triggers)

***

<div id="there-is-a-product-or-offer-issue">
  ## 存在商品或优惠问题
</div>

即使小组件已启用、位置正确且触发器匹配，优惠本身也可能在显示之前被过滤掉。

<AccordionGroup>
  <Accordion title="Upsell 商品缺货">
    如果该商品的库存被跟踪且没有任何变体可供销售，优惠将不会显示。请确保 upsell 商品至少有一个变体有可用库存，或使用不跟踪库存的商品。
  </Accordion>

  <Accordion title="Upsell 商品处于草稿（Draft）或已归档（Archived）状态">
    Upsell 商品必须是已上架、可销售的商品。在 Shopify 中处于 **Draft** 或 **Archived** 状态的商品会被过滤掉，不会作为优惠出现。请在 Shopify 后台打开该商品并确认其状态为 **Active**。
  </Accordion>

  <Accordion title="Upsell 商品已在购物车中且启用了'已在购物车中则隐藏'">
    **Hide offer if product already in cart** 设置会在该商品已在客户购物车中时隐藏优惠。对于标准商品优惠，此设置默认开启。如果你希望无论如何都显示该 upsell，请在优惠配置中停用此设置。
  </Accordion>

  <Accordion title="Upsell 商品是订阅商品但没有销售计划">
    如果 **Subscription purchase option** 设为 **Subscription**，但该商品在 Shopify 中没有配置任何销售计划（selling plan），优惠会被过滤掉。请确认该商品至少有一个有效的销售计划，或将 **Subscription purchase option** 改为 **One-time product**（其他选项是 **Subscription** 和 **Subscription and a one-time product**）。
  </Accordion>

  <Accordion title="替换型 upsell 的目标商品不在购物车中">
    如果优惠配置为替换型 upsell，它只有在要被替换的商品出现在购物车中时才会显示。请确认在替换型 upsell 配置中选择了正确的目标商品。

    当目标行项目**已应用折扣**时，替换优惠也会被跳过 — 除非你勾选 **Allow replacement if product has discount applied**；或者当目标行项目的**数量大于 1** 时，除非你勾选 **Allow replacement if product quantity greater than 1**。
  </Accordion>

  <Accordion title="已达到可接受优惠的最大数量">
    如果小组件设置了 **Max number of accepted offers**，则当客户在当前 checkout 中从该小组件接受了相应数量的优惠后，upsell 将停止显示。这是有意为之 — 一旦达到上限，小组件会自行隐藏。该字段仅适用于单商品和多商品 upsell；勾选型（Checkmark）upsell 没有此限制。
  </Accordion>

  <Accordion title="该优惠已通过此小组件添加到购物车">
    对于**单商品**和**多商品** upsell，一旦客户将优惠商品添加到购物车，优惠就会隐藏（商品已在购物车中）。\*\*勾选型（Checkmark）\*\*upsell 的行为不同 — 被接受后，它们会保持可见，且复选框处于勾选状态。
  </Accordion>
</AccordionGroup>

***

<div id="shop-pay-widgets-not-showing">
  ## Shop Pay 小组件不显示
</div>

默认情况下，checkout 小组件不会在 Shop Pay 中显示。要在 Shop Pay 中显示你的 upsell，必须显式启用：

1. 在 Shopify Checkout 编辑器中打开 Aftersell upsell 应用区块
2. 在区块设置中，找到 **Checkout behaviour** 部分
3. 勾选 **Include app block in Shop Pay** 选项
4. 保存更改

[进一步了解 Shop Pay 小组件 →](/zh/aftersell/show_checkout_widgets_in_shop_pay)

***

<div id="testing-in-the-shopify-preview">
  ## 在 Shopify 预览中测试
</div>

Shopify Checkout 编辑器预览无法可靠地渲染小组件。即使小组件配置正确，也可能不会出现在编辑器预览中，因为预览无法模拟页面标记和触发条件。请勿依赖编辑器预览来确认小组件是否正常工作。

**准确测试你的 upsell：**

1. 暂时将小组件触发器设置为 **Show for all customers**
2. 使用 Shopify 的测试支付网关（或使订单免费的折扣码）下一笔真实测试订单
3. 确认小组件在实际的 checkout 流程中显示
4. 测试完成后恢复你的触发器

***

<div id="nothing-above-applies">
  ## 以上都不适用
</div>

如果你已经排查完上述所有内容但 upsell 仍不显示，请确认以下事项：

* 小组件已在 Aftersell 中**启用**，且应用区块已在 Shopify Checkout 编辑器中**添加并保存**
* Aftersell 中的**位置**与 Shopify 中选择的位置匹配
* 触发条件与你的测试购物车匹配 — 请记住，在 **AND** 连接下，必须满足每个条件
* 至少有一个小组件在最低优先级使用 **Show for all customers** 触发器作为兜底
* Upsell 商品处于 **Active** 状态、有库存，并且（对于订阅优惠）有生效的销售计划
* 你在**真实的 checkout 流程**中测试，而不是 Shopify 编辑器预览
* 尝试清除浏览器缓存或在无痕窗口中测试 — 更改可能需要几分钟才能生效

仍未解决？请通过聊天联系我们，或发送邮件至 [support@aftersell.app](mailto:support@aftersell.app)，并附上你的小组件设置说明和测试订单详情。