Apple 的 Send Consumption Information 现在只要求五个字段,而非十二个,以下逐一解读

当客户想要退款时,Apple 向你索取的事实清单大大缩短了。Send Consumption Information 载荷,也就是开发者被允许送入 App Store 退款裁决的那唯一一次回应,过去有十二个字段,现在只有五个。Apple 在 WWDC24 前后进行了精简,把大部分旧有的账户画像式问题收拢为两个简单问题外加一个数字。字段减少并不是一处小改动。它改变了 Apple 权衡哪些证据,也改变了你绝不能填错的是哪些字段。

为什么这值得你留意,而不只是一条 schema 备注,原因在此。这份载荷是 Apple 退款流程中,你这一方的说法唯一能触及裁决的时刻。一笔消耗型退款会冲销你已经实实在在花钱交付的收入,而这五个字段正是你用来告诉 Apple 产品已交付并被使用的方式。错过 12 小时窗口,或者填错某个字段,Apple 就只凭客户一方的主张来裁定。

What Send Consumption Information is

Send Consumption Information 是 App Store Server API 的一个端点,你在 Apple 向你的服务器发送 CONSUMPTION_REQUEST 通知后调用它。该通知意味着某位客户就一笔应用内购买向 Apple 申请退款,而 Apple 想在裁定前听取你的意见。你的回应方式,是向该端点 PUT 一小段 JSON 体,即 ConsumptionRequest。Apple 读取它,与客户的历史一并权衡,然后作出决定。退款从来不由你决定。你提供事实。

这个 body 就是全部接口。没有另外的表单,没有申诉,也没有第二次能算数的提交。你在那一次载荷里发送的一切,就是你的全部陈述,因此每个字段的含义,比字段数量所暗示的更为重要。

The five fields Apple asks for now

当前的 ConsumptionRequest 有五个成员。三个必填,两个可选。Apple 过去就客户账户所问的一切,他们的账龄、终身消费、终身退款、游玩时长,都已从你所发送的内容中移除。

customerConsented is the gate

customerConsented 是一个 Boolean,也是决定你是否发送任何内容的字段。它记录客户是否同意让你向 Apple 共享消耗数据。Apple 的指引很直接:如果客户未同意,就不要发送消耗信息。所以这不是一个你为了强化己方论据而翻成 true 的字段。它反映的是一个你必须早已握有的真实是与否,这里为 false,就意味着载荷的其余部分都不应发送。

deliveryStatus is the field that moves refunds

deliveryStatus 是一个字符串枚举,也是你手中最有力的杠杆。它告诉 Apple 你的应用是否真的交付了可用的应用内购买。一个取值表示是。另外四个表示否,各自对应不同原因,而每一个都告诉 Apple 客户有正当的不满。

sampleContentProvided answers a fairness question

sampleContentProvided 是一个 Boolean。它记录你是否在客户购买前给过他们免费样品、试用,或关于该购买作用的明确说明。这里为 true 是一个小小的公平性信号:客户有机会了解自己在买什么。它本身不决定任何事,但它是仅有的三个必填字段之一,可见 Apple 明确希望每次回应中都有它。

consumptionPercentage is a number now, not a status

这是变化最大的字段。旧载荷有 consumptionStatus,一个四档枚举:UNDECLARED、NOT_CONSUMED、PARTIALLY_CONSUMED、FULLY_CONSUMED。新载荷用 consumptionPercentage 取而代之,这是一个以 milliunits 计量的整数。100,000 milliunits 表示商品已被完全消耗,那么 50,000 就是一半,0 就是分毫未动。一个精确的数字胜过四选一的分档,因为它让你能说客户用掉了某个额度包的百分之九十,而不是向下取整成部分消耗。

有一个常让人栽跟头的注意事项。对于自动续期订阅,Apple 会根据已过时间自行算出消耗量,因此 consumptionPercentage 适用于消耗型和非续期购买。在适用之处发送它,在不适用之处交由 Apple 推导。

refundPreference states a preference, not a verdict

refundPreference 是一个可选字符串,你在这里告诉 Apple 你偏好的结果。它的形态也变了。旧字段是一个数字,取值类似 prefer-grant、prefer-decline 和 no-preference。新字段是一个具名字符串,带三个取值。

What Apple dropped, and why it matters

旧的 ConsumptionRequest 有十二个字段。其中七个已从你所发送的内容中消失。accountTenure、lifetimeDollarsPurchased、lifetimeDollarsRefunded、playTime、userStatus、platform 和 appAccountToken 构成载荷中账户画像的那一半,这些字段要求你按客户拥有账户的时长、花了多少钱、被退了多少款、使用应用多久来给他们分档。

Apple 删掉它们的理由值得一提。那些字段要求开发者交出一份客户画像,而大多数开发者要么把它们留作未声明,要么靠猜。留下的五个关乎购买与交付,是你真正能从自己系统中核实的事实。这一转变,是从客户是谁,转向这笔具体购买发生了什么。

The endpoint and the clock

你通过 HTTP PUT 向 Send Consumption Information 端点发送载荷,以争议购买的交易 id 为键:PUT /inApps/v1/transactions/consumption/{transactionId}。成功会返回 202 Accepted,且响应体为空。那个空回应是意料之中,而非 bug。它确认 Apple 已将你的数据排入队列,却不告诉你最终结果如何,那要稍后以 REFUND 或 REFUND_DECLINED 通知的形式到来。

时限是你无法拉长的部分。Apple 给你从 CONSUMPTION_REQUEST 起算的 12 小时来回应。只有你的第一次回应会被采用,所以第一份载荷就必须是完整且正确的那一份。Apple 可能就同一笔购买多次发送 CONSUMPTION_REQUEST,但每一次的截止时间都是固定的,而人工审核在跨时区和周末的情况下,很难塞进 12 小时之内。

What a mishandled field costs you

The money left the building before the refund did

一笔消耗型退款不是干净利落的冲销。等到客户就一包额度或一批 AI 生成申请退钱时,你早已为交付它花了钱:每次请求上的 GPU 推理、按 token 计费的第三方模型 API 调用、为你所产出内容付出的存储,以及与该使用挂钩的任何创作者或合作方分成。商店售价退回给客户。你的交付成本却不会退回给你。所以一笔本可申辩的退款,不是一次不赔不赚的事件,而是你为服务该账户所付出的一切净亏损。

The five fields are how you avoid paying twice

deliveryStatus 设为 DELIVERED,加上较高的 consumptionPercentage,是告诉 Apple 客户已收到并使用了产品的两项事实。它们是你证明算力、API 调用和存储都各尽其责的证据。若把载荷留着不发,Apple 就永远听不到这些。它会凭客户的主张来裁定,退款更有可能通过,而你要同时吞下被冲销的收入和其背后的交付成本。

Chargebacks are the worse door, and silence points to it

一位无法通过 Apple 退款流程得到满意结果的客户,仍可向其银行就该笔扣款发起争议。银行卡拒付是最终的,它带有一笔固定的争议费,并把决定权从 Apple 和你手中一并夺走。妥善回应 CONSUMPTION_REQUEST,能让争议留在 Apple 的体系之内,你在那里还有发言权。对它置之不理,则会把处于两可之间的案子推向你毫无发言权的那唯一渠道。

How RefundHalt handles it

这五个字段看着简单,直到你必须在 12 小时之内、对每一次 CONSUMPTION_REQUEST、以正确的交易为键,把它们填对。RefundHalt 捕获通知,读取你自己关于那笔购买的交付与使用记录,并在窗口关闭前自动发送载荷。deliveryStatus 反映你日志真正显示的情况,consumptionPercentage 来自真实使用而非猜测,refundPreference 遵循你一次设定好的政策。你得到的是一笔以证据受审的可申辩退款,而非一个错过的截止时间和一份没有你参与就作出的决定。