Toda solicitação de reembolso da Apple agora vem com um motivo, e o consumptionRequestReason é como você o lê
Desde a WWDC24, todo CONSUMPTION_REQUEST da Apple carrega um consumptionRequestReason, o motivo declarado pelo próprio cliente para querer o reembolso. São cinco valores, de UNINTENDED_PURCHASE a LEGAL, e cada um deve mudar o que você envia de volta dentro da sua janela de 12 hours. Veja como ler cada um deles.
Principais conclusões
- Desde a versão 2.11 do App Store Server Notifications, anunciada na WWDC24, toda notificação CONSUMPTION_REQUEST inclui o consumptionRequestReason, uma string que informa por que o cliente pediu o reembolso.
- São exatamente cinco valores: UNINTENDED_PURCHASE, FULFILLMENT_ISSUE, UNSATISFIED_WITH_PURCHASE, LEGAL e OTHER. A Apple envia um por solicitação.
- O motivo não decide o reembolso. É o contexto que você usa para escolher seu refundPreference e seus dados de consumo antes que a janela de 12 hours se feche.
- O CONSUMPTION_REQUEST agora também dispara para assinaturas com renovação automática, não apenas para consumíveis, então o consumptionRequestReason alcança muito mais dos seus reembolsos do que alcançava antes da WWDC24.
- Um motivo FULFILLMENT_ISSUE é um sinal de que a sua própria entrega pode ter falhado. Contestá-lo queima a janela e convida um estorno mais tarde. Conceder costuma ser a resposta mais barata.
- Você responde chamando o Send Consumption Information dentro de 12 hours com customerConsented definido como true e um refundPreference de GRANT_FULL, GRANT_PRORATED ou DECLINE. A Apple trata sua preferência como uma entrada, não como uma ordem.
- Um reembolso ainda custa a você a computação, as chamadas de API, o armazenamento e os pagamentos que a compra já consumiu. O campo do motivo é como você gasta sua defesa apenas nos casos que valem a pena defender.
A Apple mudou a forma como as solicitações de reembolso chegam ao seu servidor, e muitos desenvolvedores nunca perceberam. Desde a atualização 2.11 do App Store Server Notifications anunciada na WWDC24, toda notificação CONSUMPTION_REQUEST carrega um campo chamado consumptionRequestReason. É o motivo declarado pelo próprio cliente para pedir o dinheiro de volta. Uma string simples, cinco valores possíveis, entregue dentro da mesma carga útil que você já tem doze horas para responder.
O motivo da solicitação de reembolso da Apple não decide nada sozinho. O que ele faz é dizer em qual de cinco situações muito diferentes você está, para que você pare de enviar os mesmos dados de consumo genéricos a um reembolso que deveria conceder e a um reembolso que deveria contestar. Veja o que é o campo, os valores exatos que a Apple pode enviar, o que cada um sinaliza e como ele deve mudar a preferência e as provas que você devolve.
O que consumptionRequestReason realmente é
consumptionRequestReason é um campo de string no objeto data de uma notificação CONSUMPTION_REQUEST. A Apple o adicionou na versão 2.11 do App Store Server Notifications, junto com as mudanças da WWDC24 no fluxo de reembolso. Antes disso, a solicitação chegava com a transação assinada e nada sobre o motivo. Você respondia às cegas. Agora o motivo declarado pelo cliente viaja junto com a solicitação.
Leia a palavra declarado com atenção. Este é o motivo que o cliente selecionou quando abriu a solicitação junto à Apple, não um fato que a Apple verificou. UNINTENDED_PURCHASE não prova que a compra ficou sem uso, e UNSATISFIED_WITH_PURCHASE não prova que o produto estava com defeito. O valor é uma lente, não um veredito. Você ainda o combina com seus próprios registros de entrega e de uso.
Ele viaja na notificação que você já trata
CONSUMPTION_REQUEST é o único fluxo da Apple que pede provas ao desenvolvedor. Seu equivalente no Google Play é a revisão de estorno por meio do orders.reviewrefund. Quando um chega, você tem 12 hours para responder chamando o Send Consumption Information, um PUT para o endpoint de consumo de transações. O consumptionRequestReason agora faz parte dessa mesma notificação, então não há nada novo para assinar. Se você já analisa o CONSUMPTION_REQUEST, o motivo é um campo que você provavelmente estava ignorando.
Os cinco motivos, e o que cada um está lhe dizendo
A Apple documenta exatamente cinco valores. Chega um por solicitação. Veja o conjunto completo e como ler cada um na prática.
| Valor | O que o cliente declarou | O que geralmente significa para você |
|---|---|---|
| UNINTENDED_PURCHASE | Não pretendia comprar | Muitas vezes um toque acidental ou familiar. Verifique a entrega e o consumo antes de decidir. |
| FULFILLMENT_ISSUE | Não conseguiu receber ou usar | Aponta de volta para a sua própria entrega. Verifique seus registros antes de contestar. |
| UNSATISFIED_WITH_PURCHASE | Não ficou satisfeito | Arrependimento do comprador. Aqui suas provas de consumo têm o maior peso. |
| LEGAL | Citou um motivo legal | Trate como uma concessão. Contestar uma solicitação legal não vale a janela. |
| OTHER | Qualquer motivo não listado acima | Nenhum sinal por si só. Recorra aos seus dados de entrega e de uso. |
UNINTENDED_PURCHASE é a categoria do toque acidental
Este é o motivo que um pai seleciona depois que uma criança comprou 10,000 moedas, ou um adulto que apertou por engano um botão de confirmar. Ele se correlaciona com compras que nunca foram abertas nem usadas. É exatamente por isso que seus próprios dados importam. Se seus registros mostram que o consumível foi totalmente entregue e amplamente consumido, uma reclamação de compra não intencional e um saldo totalmente gasto não combinam, e essa lacuna vale a pena reportar por meio do consumptionPercentage.
FULFILLMENT_ISSUE aponta de volta para você
FULFILLMENT_ISSUE é o único motivo que trata em parte do seu app, não do cliente. Significa que ele diz que não conseguiu receber ou usar o que pagou. Antes de contestar por reflexo, puxe seus registros de entrega. Se o seu próprio servidor mostra que o direito nunca foi ativado, ou que os créditos nunca foram lançados, o cliente está certo, e DECLINE é a preferência errada. Brigar contra uma falha de entrega real desperdiça a janela e pode empurrar o cliente para o banco, onde um estorno custa mais do que teria custado o reembolso.
UNSATISFIED_WITH_PURCHASE é onde as provas decidem
Este é o arrependimento comum do comprador, e é o motivo em que seus dados de consumo fazem o maior trabalho. O produto funcionou. O cliente usou parte ou tudo e agora quer o dinheiro de volta. Um consumptionPercentage alto, um deliveryStatus honesto de DELIVERED e um refundPreference de DECLINE ou GRANT_PRORATED é o caso que a Apple está pedindo que você apresente. Envie os números, não um argumento.
LEGAL e OTHER
LEGAL significa que o cliente invocou um direito legal ou regulatório. Pessoas razoáveis discordam, mas via de regra esta não é a janela para litigar. Conceda e siga em frente. OTHER é o coringa que a Apple usa quando o motivo declarado não se encaixa em nenhum dos quatro acima. Ele não carrega sinal algum por si só, então trate um OTHER exatamente como trataria uma solicitação sem motivo nenhum: comece pelo seu status de entrega e pelas suas provas de uso.
Como o motivo muda sua resposta, campo por campo
Você responde a um CONSUMPTION_REQUEST chamando o Send Consumption Information com um corpo ConsumptionRequest. O motivo deve moldar três campos desse corpo.
customerConsented tem que ser true
A Apple só aceita o envio quando customerConsented é true, ou seja, quando o cliente concordou em compartilhar os dados de consumo. Se você não tiver esse consentimento, não pode enviar dado algum, independentemente do motivo. Sem consentimento, sem provas, e a solicitação é decidida sem os seus números.
deliveryStatus e consumptionPercentage carregam os fatos
deliveryStatus informa se você entregou uma compra funcional. Se for qualquer coisa diferente de DELIVERED, a Apple exige que consumptionPercentage seja 0. Quando você de fato entregou, consumptionPercentage é um inteiro em milliunits de 0 a 100,000, onde 100,000 significa que o cliente usou a compra inteira. Esse par é o seu núcleo factual, e é o que deve sustentar um caso de FULFILLMENT_ISSUE ou de UNSATISFIED_WITH_PURCHASE, não o motivo em si.
refundPreference é a sua única alavanca
refundPreference é onde você declara o que quer. A Apple documenta três valores: GRANT_FULL, GRANT_PRORATED e DECLINE. Leia o motivo, pondere-o em relação aos seus dados e então escolha. Um FULFILLMENT_ISSUE com uma entrega falha nos seus registros pende para GRANT_FULL. Um UNSATISFIED_WITH_PURCHASE sobre um produto totalmente consumido pende para DECLINE ou GRANT_PRORATED. LEGAL pende para GRANT_FULL.
O que um reembolso realmente custa a você
O campo do motivo importa porque um reembolso raramente é apenas a venda saindo do seu balanço. Para um consumível que já foi usado, você pagou para cumpri-lo. Um pacote de créditos que chamou uma API de inferência paga, um lote de imagens geradas que queimou tempo de GPU, uma exportação armazenada que ocupa a sua fatura de armazenamento, um pagamento a um criador que você já enviou: esses custos continuam gastos quando a compra é revertida. A loja devolve o dinheiro do cliente. Ela não devolve a sua computação.
É por isso que vale a pena ler o motivo. Digamos que um cliente comprou 5,000 créditos que cada um dispara uma chamada de API paga, gastou 4,000 deles e então abriu a solicitação sob UNSATISFIED_WITH_PURCHASE. Seu deliveryStatus é DELIVERED, seu consumptionPercentage é 80,000 milliunits, e uma preferência DECLINE ou GRANT_PRORATED é a diferença entre engolir a fatura da API e recuperar a maior parte dela. Agora inverta o motivo para FULFILLMENT_ISSUE com registros mostrando que os créditos nunca foram lançados, e a jogada honesta e mais barata é GRANT_FULL antes que o cliente escale para o banco.
Ler o motivo sem reagir demais
A armadilha é tratar o motivo como prova. UNINTENDED_PURCHASE não é uma confissão de que o produto ficou sem uso, e LEGAL nem sempre é uma reivindicação legal genuína. O motivo estreita a situação. Seus registros de entrega e de consumo a resolvem. Quando eles concordam com o cliente, conceda cedo e barato. Quando contradizem o cliente, essa contradição, expressa como deliveryStatus e consumptionPercentage, é a coisa mais forte que você pode enviar. O RefundHalt lê o consumptionRequestReason em cada CONSUMPTION_REQUEST e o combina automaticamente com seus dados de uso reais, para que cada motivo receba a resposta que merece dentro da janela de 12 hours.
A mudança é pequena e fácil de passar despercebida, mas moveu a conversa do reembolso a seu favor. A Apple agora está lhe dizendo por quê, antes de você responder. Aproveite.
Perguntas frequentes
- O que é consumptionRequestReason?
- consumptionRequestReason é um campo de string que a Apple inclui em toda notificação CONSUMPTION_REQUEST, adicionado na versão 2.11 do App Store Server Notifications na WWDC24. Ele informa o motivo declarado pelo próprio cliente para solicitar o reembolso, dando a você contexto antes de responder com dados de consumo dentro da janela de 12 hours.
- Quais são os valores possíveis de consumptionRequestReason?
- São cinco: UNINTENDED_PURCHASE, FULFILLMENT_ISSUE, UNSATISFIED_WITH_PURCHASE, LEGAL e OTHER. A Apple envia exatamente um por solicitação de reembolso. Cada um aponta para uma situação diferente, de um toque acidental a um motivo legal declarado, e cada um deve moldar o refundPreference e os dados de consumo que você devolve.
- O motivo do reembolso decide se eu fico com o dinheiro?
- Não. consumptionRequestReason é contexto, não um veredito. A Apple ainda decide o reembolso, ponderando seu refundPreference, seu deliveryStatus e consumptionPercentage, e o histórico do cliente. O motivo diz qual caso apresentar. Seus dados de entrega e de uso são o que o apresenta.
- Quanto tempo tenho para responder a um CONSUMPTION_REQUEST?
- Você tem 12 hours desde o recebimento da notificação CONSUMPTION_REQUEST para chamar o Send Consumption Information. A chamada precisa definir customerConsented como true, ou a Apple a rejeita. Perca a janela e o reembolso é decidido sem nenhum dos seus dados.
- O consumptionRequestReason aparece nos reembolsos de assinaturas?
- Sim. A mesma atualização da WWDC24 que adicionou o consumptionRequestReason também passou a enviar CONSUMPTION_REQUEST para assinaturas com renovação automática, não apenas para consumíveis. Para a maioria dos apps isso significa que o campo do motivo agora alcança os reembolsos que mais importam financeiramente.
Fontes e leituras adicionais
RefundHalt
O piloto automático de reembolsos para App Store e Google Play
Continue lendo
A revisão de estorno do Google Play te dá 24 horas para reagir, veja o que enviar
Quando um banco reverte uma cobrança do Google Play, o Google envia ao seu servidor uma PendingRefundReviewNotification e inicia um relógio de 24 horas. Responda por meio da ReviewRefund API com uma preferência de reembolso e evidências de consumo reais, ou a disputa é decidida sem você. Aqui está todo o fluxo, campo por campo.
Anexe um appAccountToken a cada compra na App Store, ou você não conseguirá defender o reembolso
A Apple envia ao seu servidor um CONSUMPTION_REQUEST quando um cliente pede reembolso, mas a transação nunca diz quem ele é. O appAccountToken é o UUID que liga uma compra de volta ao seu usuário. Configure-o e você poderá responder à Apple com dados reais. Pule essa etapa e você estará adivinhando.