Se você já trabalhou com o fluxo de reembolso da Apple, provavelmente já viu a janela de resposta de 12 horas mencionada na documentação. O que nem sempre fica claro é como realmente responder.
O CONSUMPTION_REQUEST é uma notificação; a resposta é uma chamada a uma API diferente, com sua própria chave e um corpo que mudou de formato duas vezes desde 2021. Já abordamos o que a própria notificação contém há um tempo. Esta é a parte que vem depois, quando você realmente precisa respondê-la.
Principais Pontos
É uma única solicitação PUT para a App Store Server API. Esse é todo o mecanismo.
Cada solicitação é assinada com um JWT gerado a partir da sua chave de compra no app; tokens com mais de 60 minutos são rejeitados.
O corpo da v2 tem cinco campos, três deles obrigatórios.
A Apple responde 202 e nada mais. A decisão sobre o reembolso chega depois, como uma notificação separada.
Doze horas a partir do momento em que a notificação chega, e você pode reenviar dentro dessa janela.
O Que É uma Apple Consumption Request?
Por trás do jargão, uma Apple consumption request é, na verdade, uma pergunta. Um cliente pediu à Apple o dinheiro de volta, e antes de responder a ele, a Apple recorre ao seu servidor e pergunta: essa pessoa recebeu o que pagou, e chegou a usar?
A Apple combina o que você informa com dados que já conhece, como a frequência com que esse cliente pede reembolsos, e decide por conta própria.
As pessoas erram constantemente nesse último ponto. Você não aprova nem nega nada; você entrega fatos.
O CONSUMPTION_REQUEST enviado pela Apple chega na URL de servidor que você cadastrou no App Store Connect, como uma notificação de servidor versão 2.
Em 2021, ela só era disparada para consumíveis. As assinaturas foram incluídas em 2024, e em dezembro de 2025 a Apple publicou a versão 2 do endpoint, cuja documentação afirma que ela cobre todos os tipos de produto, incluindo não consumíveis e assinaturas sem renovação automática. A página de referência de notificações ainda lista apenas os dois tipos originais; eu confiaria na página mais recente e construiria pensando nos quatro.
E já que estamos falando de nomenclatura: as pessoas buscam por uma Apple refund API, mas ela não existe como algo separado. Essa chamada faz parte da App Store Server API.
O Que Você Precisa Antes de Poder Enviar
Três desses quatro itens não podem ser resolvidos às pressas, então leia isto antes da sua primeira solicitação, não depois.
O primeiro é uma chave, especificamente uma chave de compra no app, criada no App Store Connect em Users and Access. A Apple entrega o arquivo .p8 exatamente uma vez; você também vai precisar do key ID dela e do seu issuer ID.
Segundo, alguma forma de ir de um transaction ID (o que a Apple fornece) até uma pessoa no seu banco de dados (o que você precisa). A maneira correta é o appAccountToken, definido no momento da compra, que depois retorna em todas as notificações sobre essa transação.
Se esse termo é novo para você, leia por que o appAccountToken importa para a defesa de reembolsos primeiro, porque sem esse mapeamento o restante deste post é pura teoria.
Terceiro, e esse é o item que não dá para resolver às 2h da manhã: o consentimento.
A documentação da Apple diz claramente que, se o cliente não concordou em compartilhar esses dados, você simplesmente não responde. Ela também diz, em linguagem mais jurídica, que o que conta como consentimento válido depende de onde você opera, e que a Apple não pode orientá-lo sobre isso.
Um texto de opt-in nos seus termos é o caminho mais comum, e ele precisa existir antes que a solicitação apareça.
O quarto é o próprio transaction ID, que você só obtém depois que a notificação chega e você verifica a assinatura da Apple.
Como Enviar Informações de Consumo Passo a Passo
A maioria das pessoas que pesquisa por send consumption information apple acaba na página de referência da Apple, que lista os campos e, de repente, simplesmente para. Aqui está a sequência na prática.
Comece verificando se a notificação é legítima. O signedPayload é um JWS; a App Store Server Library da Apple o verifica e retorna a transação decodificada, incluindo transactionId e appAccountToken.
Vá buscar a compra do seu lado. O que você precisa saber: nós entregamos o item, aproximadamente que fração foi usada, o cliente viu uma amostra ou um teste antes, e o que preferiríamos que a Apple fizesse.
Agora o token. Header: alg é ES256, kid é o seu key ID, typ é JWT. Payload: iss é o seu issuer ID, iat é o momento atual, exp é no máximo 60 minutos depois, aud é a string literal appstoreconnect-v1, e bid é o seu bundle ID. O guia da Apple para gerar JSON Web Tokens traz o layout exato, embora a biblioteca já monte isso para você.
Envie com PUT. A URL de produção é https://api.storekit.apple.com/inApps/v2/transactions/consumption/{transactionId}, com o JWT como Bearer token no header Authorization, e um corpo semelhante a este:
{
"customerConsented": true,
"deliveryStatus": "DELIVERED",
"consumptionPercentage": 94000,
"sampleContentProvided": false,
"refundPreference": "DECLINE"
}
A Apple responde 202 Accepted, e é só isso que você recebe. Registre o horário, o corpo e o transaction ID, porque daqui a um mês alguém vai perguntar o que informamos à Apple sobre esse caso.
Depois, você espera. A decisão chega como uma notificação REFUND ou REFUND_DECLINED. Se for REFUND, remova o conteúdo ou o direito de acesso no mesmo dia.
Então, se você está se perguntando how to submit consumption information a Apple realmente vai usar, é isso: uma solicitação, cinco campos, dentro da janela.
A Apple também permite enviar um payload atualizado dentro dessas 12 horas, então, se a primeira chamada saiu com metade do quadro, envie uma segunda.
Algumas coisas que os nomes dos campos não deixam claras. consumptionPercentage é expresso em milésimos, o que costuma confundir: 94000 significa 94 por cento, 100000 significa a totalidade, e o valor precisa ser 0 se deliveryStatus for qualquer coisa diferente de DELIVERED.
As opções para item não entregue são UNDELIVERED_QUALITY_ISSUE, UNDELIVERED_WRONG_ITEM, UNDELIVERED_SERVER_OUTAGE e UNDELIVERED_OTHER.
refundPreference é opcional e aceita GRANT_FULL, GRANT_PRORATED ou DECLINE; para GRANT_PRORATED em uma assinatura com renovação automática, não informe a porcentagem, e a Apple calcula com base no tempo restante.
A referência Send Consumption Information traz a lista completa de erros.
O Que Significam os Códigos de Resposta
Existe apenas uma resposta boa, 202. Todas as outras são a Apple dizendo o que você errou, normalmente apontando o erro pelo nome.
Os códigos 400 são os mais úteis, já que o corpo da resposta nomeia o erro.
ConsumptionPercentageOutOfRangeError quase sempre significa que alguém enviou 94 em vez de 94000.
UndeliveredConsumptionPercentageNonZeroError significa que você disse que o item nunca chegou e, ao mesmo tempo, afirmou que ele foi parcialmente usado.
InvalidCustomerConsentedError fala por si só.
Um 401 é problema do token: chave errada, expiração com mais de uma hora de diferença, um bundle ID que não corresponde, ou o relógio do servidor desalinhado o suficiente para fazer o iat parecer estar no futuro.
Um 404 significa que o transaction ID não foi encontrado, e minha primeira pergunta é sempre se uma transação de sandbox foi enviada para a URL de produção (ou o contrário).
429 é o limite de taxa (50 solicitações por segundo por app em produção, um décimo disso no sandbox); leia o header Retry-After antes de tentar novamente.
500 é um problema do lado da Apple; tente novamente mais tarde.
Como Testar no Sandbox
Testar isso é mais fácil do que parece, com uma ressalva.
Coloque uma URL de servidor de sandbox no App Store Connect, faça login com uma Apple Account de sandbox, compre algo e, em seguida, abra a tela de reembolso do seu app (beginRefundRequest) e envie uma solicitação.
O guia de testes da Apple para solicitações de reembolso explica como o ambiente de teste se comporta: escolha qualquer motivo e o reembolso é aprovado automaticamente; escolha Other e digite DECLINE e ele é recusado; digite GRANT_PRORATED para um reembolso proporcional.
A ressalva está nessas regras: o sandbox decide com base no que você digitou na tela, não no que o seu servidor enviou, então ele não consegue indicar se os seus dados convencem a Apple de alguma coisa.
O que ele consegue testar é a infraestrutura: a notificação chega, o seu PUT para api.storekit-sandbox.apple.com retorna 202, e REFUND ou REFUND_DECLINED é tratado quando aparece.
Além disso, o sandbox não envia e-mails de reembolso, então não espere por um.
Apple Refund Automation: Quando Parar de Fazer Isso Manualmente
Feito manualmente, esse trabalho significa alguém de prontidão o tempo todo esperando um alerta, rodando uma consulta e disparando cinco campos antes que o prazo de 12 horas se esgote.
Isso funciona bem quando há apenas algumas solicitações de reembolso da Apple por mês. Funciona bem menos no primeiro feriado prolongado em que ninguém está de olho.
Para automatizar solicitações de reembolso da Apple, você pega tudo o que foi descrito acima e remove a pessoa do meio do processo: a notificação chega, suas regras transformam os dados de entrega e uso em um payload, a chamada sai em minutos, a decisão é registrada no caso, e um REFUND aciona uma revogação.
Construir isso não é um projeto enorme; acompanhar as mudanças da Apple depois (a transição de V1 para v2, por exemplo) é a parte que continua custando caro silenciosamente.
Se preferir não fazer isso você mesmo, nós analisamos os serviços criados para isso em nossa comparação de ferramentas de gestão de reembolsos da Apple, incluindo onde o Refund Sensor se encaixa e onde não se encaixa.
Uma coisa que eu sempre questiono quando o assunto surge: a automação de reembolso da Apple muda o quão confiável é a sua resposta, não quem decide. Nada nessa API dá ao desenvolvedor a palavra final.
Conclusão
A chamada em si é pequena: um token assinado, um PUT, cinco campos, um 202 para registrar.
O que faz a diferença acontece em outro lugar: no consentimento que já está nos seus termos, em um appAccountToken em cada compra, em registros de uso que você consegue acessar em segundos, e em algo que acorda às 3h da manhã junto com a notificação.
Resolva essas questões, e isso deixa de ser uma correria e passa a ser algo que o seu servidor simplesmente faz.
Perguntas frequentes
É um endpoint da App Store Server API usado para responder a um CONSUMPTION_REQUEST. Você envia uma solicitação PUT com os detalhes de consumo, e a Apple retorna 202 Accepted.
Você tem 12 horas a partir do momento em que o CONSUMPTION_REQUEST chega. A Apple permite que um payload atualizado seja enviado dentro dessa mesma janela de 12 horas.
Sim. A Apple permite que você envie um payload atualizado dentro da janela de 12 horas. Isso é útil quando o primeiro envio estava incompleto.
Não. Um 202 Accepted significa apenas que a Apple recebeu suas informações. O resultado chega depois, como uma notificação REFUND ou REFUND_DECLINED.
Sim. O campo customerConsented é obrigatório ao enviar informações de consumo. Se o cliente não tiver consentido, a documentação da Apple diz para não responder.
