Um reembolso pela Advanced Commerce API é a única forma de um desenvolvedor iOS iniciar um reembolso, e a Apple ainda dá a palavra final

Desenvolvedores iOS comuns não conseguem reembolsar um cliente. Em junho de 2026, um App Store Commerce Engineer respondeu a uma pergunta no fórum de desenvolvedores com uma única frase: no momento, não é possível que um desenvolvedor emita um reembolso diretamente. Existe uma exceção, e ela fica dentro da Advanced Commerce API. Apps que a Apple aprova podem enviar um pedido de reembolso pela Advanced Commerce API, revogar uma assinatura com devolução do dinheiro ou pedir um valor personalizado. A Apple continua decidindo se o dinheiro sai.

O que é a Advanced Commerce API e quem tem acesso

A Apple lançou a Advanced Commerce API em 23 de janeiro de 2025. Ela processa compras In-App da Apple para catálogos excepcionalmente grandes de compras avulsas personalizadas, assinaturas e assinaturas com complementos opcionais. Você não cria cada produto no App Store Connect. Você define os SKUs no seu próprio servidor e os envia à Apple no momento da compra.

O acesso é concedido app por app. Você preenche um formulário de solicitação, e a página de elegibilidade da Apple cita três modelos de negócio que precisam ser centrais no app:

• Catálogos excepcionalmente grandes de compras avulsas, como audiolivros, aulas, cursos ou mini apps.
• Catálogos excepcionalmente grandes de conteúdo por assinatura, em que a oferta de cada criador é uma assinatura própria.
• Uma assinatura com complementos opcionais que renovam juntos como uma única compra, como canais premium ou esportes.

A Apple também permite que apps se candidatem quando outro programa exige a API. O Mini Apps Partner Program, que paga aos membros 85% das vendas In-App qualificadas em mini apps hospedados, exige a API.

Os endpoints de reembolso chegaram depois, e exigem uma assinatura

A versão 1.1, de 24 de março de 2025, adicionou Request Transaction Refund e Revoke Subscription. A página do programa da Apple diz que apps que oferecem conteúdo por assinatura também podem ser elegíveis para usar as APIs de Cancel, Revoke e Refund para tratar cancelamentos, validar conteúdo após a compra e gerenciar seus catálogos. Cada página de endpoint acrescenta a mesma condição: o seu Account Holder precisa assinar o Advanced Commerce API Addendum, e se a versão mais recente não estiver aceita, a chamada retorna um erro. É o Addendum, e não a documentação, que lista os casos de uso previstos para cada endpoint.

Os três endpoints, lado a lado

Cancel a Subscription interrompe a próxima cobrança

Cancel desativa a renovação automática. A Apple diz que o cliente mantém o acesso até o fim do período atual. Nada é reembolsado. É a escolha certa quando o cliente quer sair e já usou o tempo pelo qual pagou.

Revoke Subscription encerra tudo agora

Revoke define a renovação automática como false e revoga a assinatura com reembolso total ou proporcional. O corpo da requisição aceita refundReason, refundRiskingPreference, refundType e requestInfo. Em seguida, a Apple envia uma notificação REFUND para o seu endpoint de App Store Server Notifications V2. A instrução da Apple é específica: encerre o serviço a partir da revocationDate dessa notificação, e não o encerre antes de a notificação chegar.

Request Transaction Refund funciona item por item

Esta é a ferramenta precisa. Você envia uma lista de itens, e cada um informa um SKU, um refundReason, um refundType e uma flag revoke. Com CUSTOM, você também envia refundAmount em milésimos da moeda, então 4990 significa 4,99. Se enviar um valor com FULL ou PRORATED, a Apple rejeita com o erro 4000155. A resposta traz uma transação assinada e, para assinaturas, as informações de renovação assinadas.

A Apple aceita estes valores de refundReason: UNINTENDED_PURCHASE, FULFILLMENT_ISSUE, UNSATISFIED_WITH_PURCHASE, LEGAL, OTHER e MODIFY_ITEMS_REFUND. Um sétimo, SIMULATE_REFUND_DECLINE, serve apenas para testes no sandbox e no TestFlight, e existe porque a App Store pode dizer não.

A Apple ainda pode recusar o seu próprio pedido de reembolso

O nome do endpoint é honesto. É um pedido. Dois campos mostram onde a decisão realmente está.

refundRiskingPreference abre espaço para uma verificação de consumo

A Apple descreve refundRiskingPreference como a indicação de se a App Store pede a você dados de consumo para embasar a decisão de reembolso. O padrão é true. Quando é true, você recebe um CONSUMPTION_REQUEST sobre o seu próprio pedido de reembolso e responde por meio de Send Consumption Information. A Apple pede que os desenvolvedores respondam em até 12 horas após receber um CONSUMPTION_REQUEST. Defina como false e essa notificação não chega.

Os erros que dizem não

PendingRefundError é o que você precisa prever. Uma causa provável é um cliente que já pediu à Apple pelo Report a Problem antes de a sua equipe de suporte agir. As regras de elegibilidade da Apple exigem que esses apps ofereçam, de qualquer forma, um caminho dentro do app para pedir reembolso, seja um link para o Report a Problem, seja a API beginRefundRequest, então as duas portas ficam abertas ao mesmo tempo.

Quanto um reembolso pela Advanced Commerce API custa em dinheiro

Reembolsar por iniciativa própria parece mais barato do que brigar em uma disputa. Ainda é dinheiro saindo, e a API facilita repetir alguns erros em escala.

Impostos dentro do valor personalizado

A Apple diz que o refundAmount solicitado deve incluir impostos em todas as regiões, exceto Canadá e Estados Unidos. Uma equipe que calcula um reembolso CUSTOM a partir do preço do SKU sem impostos vai reembolsar a menos os clientes de todas as outras lojas, e depois gastar tempo de suporte para corrigir cada caso.

Custos que não voltam

• Repasses: em um catálogo de criadores ou em uma plataforma de mini apps, a parte do criador costuma ser paga na venda. Um reembolso ao cliente não a recupera.
• Licenciamento de conteúdo: taxas por título devidas a um detentor de direitos por um audiolivro ou curso podem ser disparadas pelo acesso, conforme o seu contrato, e um reembolso não as reverte.
• Computação: streaming, transcodificação e qualquer trabalho de servidor feito para a compra já estão na sua fatura.
• Chamadas de API: serviços de terceiros cobrados por requisição, de voz a inferência de modelos, continuam cobrados após o reembolso.

Total quando você queria um item

Revoke Subscription reembolsa e encerra a assinatura inteira, complementos incluídos. Se o cliente contesta só um complemento, Request Transaction Refund permite reembolsar apenas aquele SKU, com revoke ativado só para aquele item. Chamar Revoke Subscription por uma reclamação sobre um único item devolve também a receita do plano base.

Um checklist antes de ativar essas chamadas

• Confirme que o seu Account Holder aceitou o Advanced Commerce API Addendum atual, e crie um alerta para o erro que aparece quando ele expira.
• Gere um novo requestReferenceId UUID para cada requisição, e reutilize o mesmo apenas para repetir uma chamada que excedeu o tempo limite.
• Coloque as chamadas de reembolso em fila. O limite é de 5 por segundo por app, e um 429 traz um cabeçalho Retry-After em milissegundos UNIX.
• Teste recusas no sandbox com SIMULATE_REFUND_DECLINE, e lembre que os limites do sandbox são 10 por cento dos de produção.
• Decida refundRiskingPreference caso a caso, e mantenha um respondedor de consumo pronto para a janela de 12 horas quando ele continuar true.
• Encerre o acesso só quando a notificação REFUND chegar, a partir da sua revocationDate.
• Registre o motivo, o valor e o SKU de cada pedido, para que a sua própria taxa de reembolso fique visível antes da taxa que a Apple enxerga.