Shopify Tax managed mode(托管模式)有助于 Shopify 通过直接管理部分商店设置和 API 行为,为美国销售应用正确的税务行为。为确保这些设置保持一致,某些 Admin API 写入操作现在会针对托管模式的要求进行验证。
托管模式设定了 Shopify 用于保持商店内税务行为一致性的要求。在某些情况下,API 现在会阻止应用写入与这些要求相冲突的设置。在其他情况下,税务行为现在依赖于更具体的产品或商店数据,而非简单的布尔值设置。
对于应用开发者而言,主要模式如下:
- 已使用所需设置的请求,或未包含应用无需管理的设置的请求,将继续正常工作。
- 尝试覆盖托管模式要求的请求现在可能会返回验证错误。
这些更改会影响为使用 Shopify Tax 托管模式的商店配置市场、发布产品、创建自定义行项目或预览结账品牌的应用。这些更改分为四类:
- 破坏性变更:当 Markets API 写入和产品发布写入与 Shopify Tax 托管模式要求冲突时,现在可能会失败。
- 弃用:taxable在自定义行项目上已弃用,建议改用productCategoryId。
- 新功能:应用可以在草稿订单和订单编辑中为自定义行项目分配产品类别。
- 行为澄清:结账页脚可见性控制仅适用于商户可配置的内容,不适用于 Shopify 提供的交易信息。
破坏性变更:Market API 写入需要固定的美国默认值
对于在美国销售中使用 Shopify Tax 托管模式的商店,marketCreate和marketUpdate突变现在会拒绝尝试覆盖受影响市场的必需货币和税收显示默认值的操作。此验证仅适用于包含美国的商户管理型非零售市场。不包含美国的市场、零售市场和第三方管理型市场则被排除在外。
即使向美国客户销售商品,未使用 Shopify Tax 托管模式的商店也不会受到影响。
受影响的请求
此变更适用于所有受支持的 API 版本,包括unstable。仅当请求提供currencySettings或priceInclusions时才应用验证,因此省略这些输入的请求保持不变。当提交其中一个输入时,Shopify 会验证最终设置,包括保留的值和省略子字段的默认值。
如果您的应用设置了这些字段,请使用所需的默认值,或者省略您的应用无需管理的字段。
对于仅面向美国的市场,以下可选输入将使用所需的默认值:
{ "currencySettings": { "baseCurrency": "USD", "localCurrencies": false }, "priceInclusions": { "taxPricingStrategy": "ADD_TAXES_AT_CHECKOUT" } }对于包含美国和另一个国家(如加拿大)的市场,以下可选输入将使用所需的默认值:
{ "currencySettings": { "localCurrencies": true }, "priceInclusions": { "taxPricingStrategy": "INCLUDES_TAXES_IN_PRICE_BASED_ON_COUNTRY" } }通过userErrors.code、userErrors.field和userErrors.message处理验证错误。货币违规返回UNSUPPORTED_CURRENCY。税收显示违规在 API 版本2026-07及更高版本中返回INCOMPATIBLE_CONFIGURATION,而在早期版本中返回GENERIC_ERROR。
相关文档
- 市场货币设置输入
- 市场价格包含项输入
- 市场突变错误代码
突发:发布商品需要 Shop 频道
对于使用 Shopify Tax 托管模式的商店,发布到 Online Store、Headless、Hydrogen 或 Buy Button 的产品也必须发布到 Shop。由于这些渠道依赖于 Shop,因此会导致产品在某一渠道上存在而不在 Shop 上的请求会根据 API 版本以不同方式处理。在unstable中,请求将失败。在日期标记版本中,Shopify 会将缺失的 Shop 或依赖渠道的更改添加到请求中并保存。Shopify 不会保存任何失败请求的部分内容。
下面描述的失败情况适用于unstableAPI 版本。日期标记版本适用相同的规则,但会更改请求而不是使其失败。请参阅日期标记 API 版本。不使用 Shopify Tax 托管模式的商店不受影响,且仅更改其他销售渠道、集合或产品变体的请求保持不变。该变更正在逐步推出给使用托管模式的商店,且不涉及架构变更。
受影响的请求
当商品已发布到某频道、计划在该频道发布,或(对于草稿商品)已添加到该频道时,即视为该商品位于该频道。包含 Shop 和依赖频道的请求会作为一个整体进行检查,无论顺序如何。
此验证适用于publishablePublish、publishableUnpublish和publicationUpdate。它还适用于已弃用的 GraphQL 发布 API,包括productPublish、productUnpublish以及productCreate和productUpdate上的发布字段。对于 REST Admin API,当产品创建和更新请求会使产品出现在 Online Store 上,而该产品不在 Shop 上或被 Shop 阻止时,这些请求将失败。
适用其他验证规则:
Shop 会在拒绝产品或标记其需要采取行动时阻止该产品。如果 Shop 阻止了该产品,且 resulting state 使其保留在依赖渠道上,即使请求仅发布到 Shop,publishablePublish 也会失败。productUpdate 在 Shop 阻止产品且 resulting state 使其保留在依赖渠道上时也会失败。
从 Shop 移除产品需要移除其处于任何状态的依赖渠道发布内容。这适用于 publishableUnpublish 和 publicationUpdate 从 Shop 的移除操作。
对于 publicationUpdate:
- 如果产品不在 Shop 上或被 Shop 阻止,将其添加到依赖渠道会失败。如果被阻止的产品仍保留在依赖渠道上,将其添加到 Shop 也会失败。当包含在 publishablesToAdd 中时,不会检查目标发布中已存在的产品。
- publicationUpdate 在依赖渠道上拒绝 autoPublish: true(当 Shop 的发布不自动发布时)。它还在 Shop 上拒绝 autoPublish: false(当依赖渠道仍在自动发布时)。
在 productUpdate 上,发布内容会替换产品的整个发布列表。只要替换列表中包含依赖渠道,就应包含 Shop,即使产品已经在 Shop 上也是如此。当请求还更改状态时,验证会使用新状态。
已弃用的 productPublish 和 productUnpublish 变异遵循与 publishablePublish 和 publishableUnpublish 相同的失败条件。
带日期的 API 版本
在带日期的 API 版本中,Shopify 会将违反这些规则的请求修改为符合规则,然后保存它:
- 将商品发布到依赖频道也会将其发布到 Shop。由于 Shop 不支持计划发布,因此即使依赖频道是计划发布的,Shopify 也会立即将其发布到 Shop。
- 从 Shop 移除商品也会从其依赖频道中移除该商品。
- 在 productCreate 和 productUpdate 上,包括产品级发布字段,当请求将产品置于 Online Store 或其他依赖渠道时,会添加 Shop。在 productUpdate 上,省略 Shop 的发布列表会使产品保留在 Shop 上。
- 对于 publicationUpdate,将产品添加到依赖渠道也会将它们添加到 Shop,而从 Shop 移除产品也会从依赖渠道移除它们。为依赖渠道开启 autoPublish 也会为 Shop 开启它。为 Shop 关闭 autoPublish 也会为依赖渠道关闭它。
- Shop 的拒绝或“需要操作”标志不会阻止请求。
- REST Admin API 的商品、商品列表和商品发布请求行为方式相同。
如果请求在这些更改后仍然违反规则,它将失败并显示与 unstable 中相同的错误。例如,当草稿产品在未包含 Shop 的情况下在依赖渠道上计划发布时,就会发生这种情况。
请注意:
- 如果您的应用将商品发布到 Online Store、Headless、Hydrogen 或 Buy Button,请首先将商品发布到 Shop,或在同一请求中包含 Shop。如果您的应用从 Shop 取消发布商品,请先从其依赖频道中取消发布,或将这些移除操作包含在同一请求中。
- 如果您的应用通过 REST Admin API 创建活跃产品,请发送 "published": false,然后使用 publishablePublish 将产品发布到 Shop 和 Online Store。
- 在带日期的版本中,即使您的请求未指定这些频道,Shopify 也可以将商品发布到 Shop,或从其依赖频道中移除该商品。要控制结果,请将 Shop 及其依赖频道一起发送。
将这些失败处理为验证错误。重试相同的请求会返回相同的错误。发布请求因 For the store setup, Shop publication is a prerequisite 而失败。取消发布请求因 For the store setup, unpublishing from dependent publications is a prerequisite 而失败。
相关文档
- publishablePublish
- publishableUnpublish
- publicationUpdate
- REST Admin API:商品
已弃用:自定义行项目上的 taxable
草稿订单和订单编辑中自定义行项目的 taxable 输入已弃用,取而代之的是 productCategoryId,后者从 Shopify 标准产品分类法分配类别,并让 Shopify 确定该项目的税务处理方式。
在 GraphQL Admin API 版本 2027-01 及更高版本中,DraftOrderLineItemInput.taxable 和 orderEditAddCustomItem 上的 taxable 参数被标记为已弃用。API 版本为 2026-10 或更低的应用程序不会看到架构更改。
- 读取 taxable 状态并未弃用,因此返回行项目是否可征税的字段以及包含可征税状态的 webhook 负载保持不变。
- 对于使用 Shopify Tax 托管模式的商店,taxable 在所有 API 版本的自定义行项目中均被忽略;产品类别设定税务处理方式,且没有类别的自定义行项目按标准税率征税。对于所有其他商店,taxable 仍按原有方式工作。
如果您的应用在创建或编辑自定义行项目时设置 taxable,请在 GraphQL Admin API 版本 2027-01 或更高版本中将其替换为 productCategoryId。若要豁免使用 Shopify Tax 托管模式商店中的整个草稿订单,请将客户、公司或公司位置标记为免税。使用类别可豁免单个商品。
相关文档
- DraftOrderLineItemInput
- orderEditAddCustomItem
- REST Admin API:草稿订单
新功能:在草稿订单和订单编辑中为自定义行项目设置产品类别
您现在可以为草稿订单和订单编辑中的自定义行项目分配来自 Shopify 标准产品分类法的类别。该类别以与产品相同的方式控制项目的税务处理。
对于使用 Shopify Tax 托管模式的商店,productCategoryId 是用于设定自定义行项目税务处理的输入参数。taxable 输入参数将被忽略。没有类别的自定义行项目被视为“未分类”,并按标准税率征税。
对于不使用 Shopify Tax 托管模式的商店,taxable: false 继续表示该自定义行项目不征税。当对该商品征税时,Shopify 可以使用其类别来计算税款。
受影响的请求
在草稿订单中,DraftOrderLineItemInput.productCategoryId 用于在 draftOrderCreate、draftOrderUpdate 和 draftOrderCalculate 中为自定义行项目设置产品类别;当提供 variantId 时,它会被忽略。您可以从 DraftOrderLineItem.productCategory 和 CalculatedDraftOrderLineItem.productCategory 读取保存的类别;这些字段针对产品变体行项目返回 null。
在订单编辑中,orderEditAddCustomItem 接受新的 productCategoryId 参数。您可以从 CalculatedLineItem.productCategory 读取类别。
如果 productCategoryId 与当前分类法中的任何类别都不匹配,则该变更操作将返回用户错误。
产品类别可以表达简化的税率、豁免以及是非型 taxable 值无法涵盖的特定于类别的税务规则。要使用它,请通过 taxonomy 查询查找类别 ID,将该 ID 作为 productCategoryId 传递,并从相关的 productCategory 字段读取保存的类别。
query { taxonomy { categories(search: "t-shirts", first: 5) { nodes { id fullName } } } }相关文档
- DraftOrderLineItemInput
- DraftOrderLineItem
- CalculatedDraftOrderLineItem
- orderEditAddCustomItem
- CalculatedLineItem
- TaxonomyCategory
- taxonomy
说明:结账页脚可见性控件仅管理商家可配置的内容
CheckoutBrandingFooterContent 和 CheckoutAndAccountsConfigurationBrandingFooterContent 上的可见性字段现在仅控制商家可配置的页脚内容。当可见性设置为 HIDDEN 时,所有结账页面和感谢页面均可在页脚中显示 Shopify 提供的额外交易信息。
商家可配置的页脚内容包括商家政策链接和版权声明。由 Shopify 提供的交易信息属于结账流程的一部分,不受结账品牌设置的管控,也无法通过这些可见性设置进行配置。
这会影响通过旧版结账品牌 API 或结账与账户配置 API 为 Shopify Plus 商店定制结账品牌的插件,尤其是那些管理页脚可见性、渲染品牌预览或运行视觉测试的插件。不管理结账页脚可见性的插件不受影响。
没有字段、输入类型、枚举值、访问范围或变更发生任何改变。此说明适用于存在相应品牌类型的每个 GraphQL Admin API 版本;它不与新的 API 版本绑定。
现有的变更操作和存储的品牌配置继续正常工作,无需更改。如果您的插件会预览或测试结账品牌,请对其进行更新,以便在隐藏商家可配置的页脚内容时,仍能让由 Shopify 提供的交易信息保持可见。
相关文档
- CheckoutBrandingFooterContent
- CheckoutBrandingFooterContentInput
- CheckoutAndAccountsConfigurationBrandingFooterContent
- CheckoutAndAccountsConfigurationBrandingFooterContentInput

