税务豁免

如果您向经销商、政府机构或非营利组织销售商品，这些买家持有豁免证书，可使其在特定州免征销售税。Zonos 将这些证书存储在客户档案中，以便在结账时识别符合豁免条件的买家。

豁免按辖区记录。在南卡罗来纳州享有豁免的客户不会在德克萨斯州自动获得豁免，因此客户持有证书的每个州都是一条单独的记录，拥有各自的日期和证书编号。

豁免依附于现有客户，因此同步分为两次调用：先创建客户，再同步其证书。两次调用都以您自己的客户 ID 为键——即您在 Checkout 其他地方使用的同一个 customerId。Zonos 从不要求您存储内部 ID。

此功能仅适用于自定义 API 集成。

创建或更新客户 

checkoutCustomerUpsert 会创建一个客户档案，如果该 customerId 已存在对应档案，则会更新该档案。与 checkoutCustomerProfileAuthenticate 不同，此调用不要求买家在场，因此您可以提前配置好客户列表。有关字段行为的完整说明，请参阅在没有买家的情况下创建或更新档案。

因为它以 customerId 进行匹配，重复调用会更新同一个档案，而不会产生重复记录。可以放心地对整个客户列表在每次同步时都运行一遍。

同步税务豁免 

checkoutCustomerTaxExemptionsSync 一次可接受多个客户。每个条目都会替换该客户的完整豁免集合。

省略 expiresAt 表示该证书没有到期日。省略 exemptionReason 默认取值为 UNSPECIFIED。

同步的工作方式 

三条规则支配每次同步。

列表是权威依据。 taxExemptions 是客户的完整豁免集合，而不是变更列表。已记录在案但未出现在列表中的豁免会被移除——这正是一份被撤销的证书停止生效的方式。发送不完整的列表会悄无声息地移除其中未包含的所有内容。

每条记录都是一项豁免。 无法记录客户在某地不享有豁免——见下方说明。

移除全部豁免即发送空列表。 要清除客户的证书，请以 "taxExemptions": [] 发送。将客户完全排除在请求之外，则其现有记录保持不变。

豁免原因 

exemptionReason 描述客户享有豁免的原因。它是可选的，默认取值为 UNSPECIFIED，但提供该字段是值得花力气的——见下文。

原因分为两类，区别很重要。基于实体的原因——政府、慈善、宗教、教育——无论买家购买什么都可豁免。基于用途的原因，RESALE 最为典型，仅覆盖符合条件的商品：转售证书覆盖买家将转售的库存，而不覆盖同一订单中的办公家具。

如果没有提供原因，Zonos 无法区分这两类，只能对整个订单进行豁免，这对转售证书而言是最难站得住脚的。如果您的大多数豁免都是转售类型，将 RESALE 设为默认值并单独列出例外情况，通常比对每个客户逐一分类要省力得多。

豁免参考编号 

exemptionReference 是客户豁免文件上印制的编号。根据州和豁免类型的不同，它可能是转售或卖方许可证编号、州豁免证书编号、直接付款许可证编号或联邦税号。

每条记录都必须提供该字段。请完全按照证书上显示的样式存储和发送——不同辖区的格式差异很大（SR EAA 12-345678、85-8012345678C-9、12-3456789），Zonos 会保留发送时的值，仅去除首尾多余的空格。请勿更改大小写或去除连字符和空格。

被拒绝的记录 

记录会被逐条验证。被拒绝的记录会在 rejected 中报告，不会导致批次中的其余记录失败，也不会影响该辖区已记录在案的豁免。

未知客户会被拒绝而非被创建，因此拼写错误的 customerId 会在响应中显现出来，而不会创建一个永远匹配不到真实买家的档案。

仅验证美国的行政区划。其他国家的下级行政区划会按发送时的原样被接受。

读取和移除 

读取客户的豁免记录以确认同步已生效：

要移除客户的全部豁免——例如客户注销账户时——请使用 checkoutCustomerTaxExemptionsDelete。无论客户是否曾有豁免记录，它都会返回 SUCCESS，因此可以安全地多次调用。