服务对象与地域限制
PuppyIP 仅面向海外合规企业及其授权人员提供服务，不面向中国大陆地区开放或提供代理服务。本服务仅限用于中国大陆境外的合法业务活动，严禁在中国大陆境内使用本服务。
代理 IP 或服务器位于境外，不改变上述限制。不得通过中转、转接、共享或转售向中国大陆境内的最终使用者提供本服务。使用前请阅读用户服务协议。
本文要点
- `note` 是入账与扣减输入中的可选字段；不采用备注的现有集成无需改动。
- 备注仅供商家查看，只能随交易创建，已存在交易的备注不能编辑。
- 备注上限为 5,000 个字符；超长会产生 NOTE_TOO_LONG 错误，且不创建交易。
- 入账、扣减和扣减冲正可读回备注；未设置时为 null，过期交易始终为 null。
先确认这项变更是否适合你的版本
如果你要在 Shopify 商店储值（store credit）的入账或扣减交易中记录仅商家可见的信息，这项变更提供了可选的 `note`。现有集成不需要添加字段，也不必为了继续处理交易而修改。
该能力适用于 GraphQL Admin API 2027-01 及以后版本。截至 2026 年 11 月 6 日，2026-10 是最新稳定版，2027-01 还是候选版。候选内容可能变化，Shopify 不建议在生产环境使用候选版；无需为了备注强制切换线上版本。
备注在交易中的作用和边界
`StoreCreditAccountCreditInput` 与 `StoreCreditAccountDebitInput` 都接受可选的 `note` 字符串。备注随新建的入账或扣减交易保存；`StoreCreditAccountTransaction.note` 可用于读回保存值。该备注只供商家查看，不会向顾客显示。
备注只能在创建交易时设置，不能编辑已有交易的备注。商家可选择用它记录便于内部识别的交易上下文，例如内部订单引用或对账提示；它只是备注，不会替代你自己的对账记录，也不会单独证明交易状态。
采用前核对现有权限
2026-10 及更早的 GraphQL Admin API 版本不提供这些字段；新字段从 2027-01 起可用。现有的 `read_store_credit_account_transactions` 与 `write_store_credit_account_transactions` 访问范围和权限要求继续适用，不需要新增 scope。入账 mutation 的参考文档要求 `write_store_credit_account_transactions`。
超长备注会阻止交易创建
备注最多 5,000 个字符。超过上限时，API 返回 `NOTE_TOO_LONG` 用户错误，并且不会创建该笔交易。记录成功之前，应检查该次请求的用户错误和返回的交易对象，而不是只保存自己提交的备注文本。
在开发商店验证后再评估上线
如需采用此功能，可先在开发商店使用支持该字段的 API 版本，准备一段容易识别的测试备注。创建一笔测试入账或扣减时传入 note，然后读取交易上的 note，核对保存值与测试值是否一致。
建议把正常备注和超长备注分开验证：前者检查保存与读取，后者检查是否收到 NOTE_TOO_LONG 且没有创建交易。记录实际 API 版本、交易对象和用户错误，供应用的开发与支持人员复核；不要只以请求发出或备注文本存在作为完成依据。
测试通过不代表应立即把生产应用切到候选版。先保持既有请求行为；待包含该字段的稳定版本发布后，再按应用自己的版本升级流程评估采用，并在开发环境复核写入与读取。若暂时不需要商家备注，可以继续不传该可选字段。
资料来源
常见问题
交易的 note 为 null，是否说明请求失败？
不一定。未设置备注时，入账、扣减和扣减冲正交易会返回 null；过期交易始终返回 null。还需查看实际交易对象和该次请求的用户错误。
指定了 API 版本，为什么实际响应仍可能缺少新字段？
检查响应的 X-Shopify-API-Version，确认实际处理请求的版本。Shopify 会把已不可用版本的请求交给最早仍可用的稳定版本。备注字段要求 2027-01 或更高版本；截至本文日期，2026-10 仍是最新稳定版。不要仅凭请求中填写的版本推定新字段已经生效。