O Send Consumption Information da Apple agora pede cinco campos, não doze, e aqui está cada um

A lista de fatos que a Apple pede quando um cliente quer um reembolso ficou bem mais curta. A carga do Send Consumption Information, a única resposta que um desenvolvedor pode enviar para uma decisão de reembolso da App Store, costumava ter doze campos. Agora tem cinco. A Apple a enxugou por volta da WWDC24 e condensou a maioria das antigas perguntas de perfilamento de conta em duas simples e um número. Menos campos não é uma edição pequena. Muda quais evidências a Apple pondera e muda quais campos você não pode errar.

Aqui está o motivo pelo qual isso merece a sua atenção e não é apenas uma nota sobre o esquema. Essa carga é o único momento em um reembolso da Apple em que o seu lado da história chega à decisão. Um reembolso de um consumível reverte receita que você já gastou dinheiro real para entregar, e os cinco campos são como você diz à Apple que o produto foi entregue e usado. Perca a janela de 12 horas ou preencha um campo errado, e a Apple decide apenas com a reclamação do cliente.

O que é o Send Consumption Information

Send Consumption Information é o endpoint da App Store Server API que você chama depois que a Apple envia ao seu servidor uma notificação CONSUMPTION_REQUEST. Essa notificação significa que um cliente pediu à Apple um reembolso de uma compra dentro do app e a Apple quer a sua contribuição antes de decidir. Você responde enviando com um PUT um pequeno corpo JSON, o ConsumptionRequest, ao endpoint. A Apple o lê, pondera contra o histórico do cliente e toma a decisão. Você nunca decide o reembolso. Você fornece fatos.

O corpo é toda a interface. Não há formulário separado, nem recurso, nem um segundo envio que conte. O que você enviar nessa única carga é o seu caso completo, então o significado de cada campo importa mais do que a quantidade de campos sugere.

Os cinco campos que a Apple pede agora

O ConsumptionRequest atual tem cinco membros. Três são obrigatórios e dois são opcionais. Tudo o que a Apple costumava perguntar sobre a conta do cliente, o tempo de conta dele, o gasto ao longo da vida, os reembolsos ao longo da vida, o tempo de uso, foi removido do que você envia.

customerConsented é a barreira

customerConsented é um booleano, e é o campo que decide se você envia alguma coisa. Ele registra se o cliente concordou que você compartilhe dados de consumo com a Apple. A orientação da Apple é direta: se o cliente não consentiu, não envie a informação de consumo. Então não é um campo que você marca como true para fortalecer o seu caso. Ele reflete um sim ou não real que você já deve ter, e um false aqui significa que o resto da carga não deve ser enviado.

deliveryStatus é o campo que move os reembolsos

deliveryStatus é um enum de string, e é a alavanca mais forte que você tem. Ele diz à Apple se o seu app realmente entregou uma compra funcional dentro do app. Um valor diz sim. Os outros quatro dizem não, cada um por um motivo diferente, e cada um diz à Apple que o cliente tem uma queixa legítima.

sampleContentProvided responde a uma pergunta de justiça

sampleContentProvided é um booleano. Ele registra se você deu ao cliente uma amostra gratuita, um teste ou informação clara sobre o que a compra faz antes de ele comprar. Um true aqui é um pequeno sinal de justiça: o cliente teve a chance de saber o que estava comprando. Ele não decide nada sozinho, mas é um de apenas três campos obrigatórios, então a Apple claramente o quer em toda resposta.

consumptionPercentage agora é um número, não um status

Este é o campo que mais mudou. A carga antiga tinha consumptionStatus, um enum de quatro passos: UNDECLARED, NOT_CONSUMED, PARTIALLY_CONSUMED, FULLY_CONSUMED. A nova carga o substitui por consumptionPercentage, um inteiro medido em milliunits. 100,000 milliunits significa que o item foi totalmente consumido, então 50,000 é a metade e 0 é intocado. Um número preciso supera um balde de quatro opções, porque permite você dizer que um cliente gastou 90 por cento de um pacote de créditos em vez de arredondar para baixo como consumido parcialmente.

Uma ressalva que confunde as pessoas. Em assinaturas com renovação automática a Apple calcula o consumo por conta própria a partir do tempo decorrido, então consumptionPercentage é destinado a compras consumíveis e não renováveis. Envie onde se aplica, e deixe a Apple derivar onde não se aplica.

refundPreference expressa uma preferência, não um veredito

refundPreference é uma string opcional, e é onde você diz à Apple qual resultado prefere. Ele também mudou de forma. O campo antigo era um número com valores como prefer-grant, prefer-decline e no-preference. O novo é uma string nomeada com três valores.

O que a Apple removeu, e por que isso importa

O ConsumptionRequest antigo tinha doze campos. Sete deles sumiram do que você envia. accountTenure, lifetimeDollarsPurchased, lifetimeDollarsRefunded, playTime, userStatus, platform e appAccountToken eram a metade de perfilamento de conta da carga, os campos que pediam para você classificar um cliente por quanto tempo ele tinha uma conta, quanto tinha gastado, quanto tinha sido reembolsado e por quanto tempo tinha usado o app.

A Apple os removeu por um motivo que vale a pena notar. Esses campos pediam aos desenvolvedores para entregar um perfil do cliente, e a maioria dos desenvolvedores ou os deixava não declarados ou os adivinhava. Os cinco que restam tratam da compra e da entrega, fatos que você realmente pode verificar a partir dos seus próprios sistemas. A mudança vai de quem o cliente é para o que aconteceu com esta compra específica.

O endpoint e o relógio

Você envia a carga com um PUT de HTTP ao endpoint do Send Consumption Information, identificado pelo id da transação da compra em disputa: PUT /inApps/v1/transactions/consumption/{transactionId}. Um sucesso retorna 202 Accepted, e o corpo da resposta é vazio. Essa resposta vazia é esperada, não um bug. Ela confirma que a Apple enfileirou os seus dados, e não diz nada sobre o resultado final, que chega depois como uma notificação REFUND ou REFUND_DECLINED.

O relógio é a parte que você não pode esticar. A Apple dá a você 12 horas a partir do CONSUMPTION_REQUEST para responder. Apenas a sua primeira resposta é usada, então a primeira carga tem que ser a completa e correta. A Apple pode enviar o CONSUMPTION_REQUEST mais de uma vez para a mesma compra, mas o prazo de cada um é fixo, e uma revisão manual raramente cabe dentro de 12 horas entre fusos horários e fins de semana.

O que um campo mal tratado custa a você

O dinheiro saiu do prédio antes do reembolso

O reembolso de um consumível não é uma reversão limpa. Quando um cliente pede o dinheiro de volta por um pacote de créditos ou um lote de gerações de IA, você já gastou para entregá-lo: inferência de GPU em cada requisição, chamadas a API de modelos de terceiros cobradas por token, armazenamento do que você produziu, e qualquer pagamento a criadores ou parceiros ligado a esse uso. O preço da loja volta ao cliente. O seu custo de entrega não volta para você. Então um reembolso que você poderia ter contestado não é um evento de ponto de equilíbrio, é uma perda líquida de tudo o que você pagou para atender a conta.

Os cinco campos são como você evita pagar duas vezes

deliveryStatus definido como DELIVERED e um consumptionPercentage alto são os dois fatos que dizem à Apple que o cliente recebeu e usou o produto. Eles são a sua prova de que a computação, as chamadas à API e o armazenamento cumpriram seu papel. Deixe a carga sem enviar e a Apple nunca fica sabendo. Ela decide a partir da reclamação do cliente, o reembolso é mais provável de passar, e você arca tanto com a receita revertida quanto com o custo de entrega por trás dela.

Os estornos são a pior porta, e o silêncio aponta para ela

Um cliente que não consegue satisfação pelo fluxo de reembolso da Apple ainda pode contestar a cobrança com o banco. Um estorno de cartão é definitivo, carrega uma taxa de disputa fixa, e tira a decisão das mãos da Apple e das suas. Responder bem ao CONSUMPTION_REQUEST mantém a disputa dentro do sistema da Apple, onde você tem voz. Ignorá-lo empurra os casos limítrofes para o único canal onde você não tem nenhuma.

Como o RefundHalt lida com isso

Os cinco campos parecem simples até você ter que preenchê-los corretamente, dentro de 12 horas, em cada CONSUMPTION_REQUEST, ligados à transação certa. O RefundHalt captura a notificação, lê os seus próprios registros de entrega e uso daquela compra, e envia a carga automaticamente antes de a janela fechar. deliveryStatus reflete o que os seus registros de fato mostram, consumptionPercentage vem do uso real em vez de um palpite, e refundPreference segue a política que você configurou uma vez. Você tem o reembolso contestável revisado com evidência, não um prazo perdido e uma decisão tomada sem você.