Cada solicitud de reembolso de Apple llega ahora con un motivo, y consumptionRequestReason es cómo lo lees
Desde la WWDC24, cada CONSUMPTION_REQUEST de Apple incluye un consumptionRequestReason, el motivo declarado por el propio cliente para pedir el reembolso. Hay cinco valores, desde UNINTENDED_PURCHASE hasta LEGAL, y cada uno debería cambiar lo que devuelves dentro de tu ventana de 12 hours. Aquí tienes cómo leer cada uno.
Puntos clave
- Desde la versión 2.11 de App Store Server Notifications, anunciada en la WWDC24, cada notificación CONSUMPTION_REQUEST incluye consumptionRequestReason, una cadena que indica por qué el cliente pidió el reembolso.
- Hay exactamente cinco valores: UNINTENDED_PURCHASE, FULFILLMENT_ISSUE, UNSATISFIED_WITH_PURCHASE, LEGAL y OTHER. Apple envía uno por solicitud.
- El motivo no decide el reembolso. Es contexto que usas para elegir tu refundPreference y tus datos de consumo antes de que se cierre la ventana de 12 hours.
- CONSUMPTION_REQUEST ahora también se activa para las suscripciones de renovación automática, no solo para los consumibles, así que consumptionRequestReason alcanza a muchos más de tus reembolsos que antes de la WWDC24.
- Un motivo FULFILLMENT_ISSUE es una señal de que tu propia entrega puede haber fallado. Impugnarlo consume la ventana e invita a un contracargo más adelante. Concederlo suele ser la respuesta más barata.
- Respondes llamando a Send Consumption Information dentro de las 12 hours con customerConsented establecido en true y un refundPreference de GRANT_FULL, GRANT_PRORATED o DECLINE. Apple trata tu preferencia como un dato más, no como una orden.
- Un reembolso te sigue costando el cómputo, las llamadas a la API, el almacenamiento y los pagos que la compra ya consumió. El campo del motivo es cómo gastas tu defensa solo en los casos que vale la pena defender.
Apple cambió la forma en que las solicitudes de reembolso llegan a tu servidor, y muchos desarrolladores nunca lo notaron. Desde la actualización 2.11 de App Store Server Notifications anunciada en la WWDC24, cada notificación CONSUMPTION_REQUEST lleva un campo llamado consumptionRequestReason. Es el motivo declarado por el propio cliente para pedir que le devuelvan su dinero. Una cadena simple, cinco valores posibles, entregada dentro de la misma carga útil que ya tienes doce horas para responder.
El motivo de la solicitud de reembolso de Apple no decide nada por sí solo. Lo que hace es decirte en cuál de cinco situaciones muy distintas te encuentras, para que dejes de enviar los mismos datos de consumo genéricos a un reembolso que deberías conceder y a un reembolso que deberías pelear. Aquí tienes qué es el campo, los valores exactos que Apple puede enviar, qué señala cada uno y cómo debería cambiar la preferencia y las pruebas que devuelves.
Qué es en realidad consumptionRequestReason
consumptionRequestReason es un campo de cadena en el objeto data de una notificación CONSUMPTION_REQUEST. Apple lo añadió en la versión 2.11 de App Store Server Notifications, junto con los cambios de la WWDC24 al flujo de reembolsos. Antes de eso, la solicitud llegaba con la transacción firmada y nada sobre el motivo. Respondías a ciegas. Ahora el motivo declarado por el cliente viaja con la solicitud.
Lee con atención la palabra declarado. Este es el motivo que el cliente seleccionó cuando presentó la solicitud ante Apple, no un hecho que Apple haya verificado. UNINTENDED_PURCHASE no prueba que la compra quedó sin usar, y UNSATISFIED_WITH_PURCHASE no prueba que el producto estuviera defectuoso. El valor es una lente, no un veredicto. Aún lo combinas con tus propios registros de entrega y de uso.
Viaja en la notificación que ya gestionas
CONSUMPTION_REQUEST es el único flujo de Apple que pide pruebas al desarrollador. Su equivalente en Google Play es la revisión de contracargo a través de orders.reviewrefund. Cuando llega una, tienes 12 hours para responder llamando a Send Consumption Information, un PUT al endpoint de consumo de transacciones. consumptionRequestReason ahora forma parte de esa misma notificación, así que no hay nada nuevo a lo que suscribirse. Si ya analizas CONSUMPTION_REQUEST, el motivo es un campo que probablemente estabas ignorando.
Los cinco motivos, y qué te dice cada uno
Apple documenta exactamente cinco valores. Llega uno por solicitud. Aquí tienes el conjunto completo y cómo leer cada uno en la práctica.
| Valor | Qué declaró el cliente | Qué suele significar para ti |
|---|---|---|
| UNINTENDED_PURCHASE | No tenía intención de comprarlo | A menudo un toque accidental o familiar. Comprueba la entrega y el consumo antes de decidir. |
| FULFILLMENT_ISSUE | No pudo recibirlo o usarlo | Apunta de vuelta a tu propia entrega. Verifica tus registros antes de impugnar. |
| UNSATISFIED_WITH_PURCHASE | No quedó satisfecho con él | Arrepentimiento del comprador. Aquí tus pruebas de consumo tienen el mayor peso. |
| LEGAL | Alegó un motivo legal | Trátalo como una concesión. Impugnar una solicitud legal no vale la ventana. |
| OTHER | Cualquier motivo no listado arriba | Ninguna señal por sí solo. Recurre a tus datos de entrega y de uso. |
UNINTENDED_PURCHASE es la categoría del toque accidental
Este es el motivo que selecciona un padre después de que un niño comprara 10,000 monedas, o un adulto que pulsó por error un botón de confirmar. Se correlaciona con compras que nunca se abrieron ni se usaron. Por eso mismo importan tus propios datos. Si tus registros muestran que el consumible se entregó por completo y se consumió en gran medida, una reclamación de compra no intencionada y un saldo totalmente gastado no concuerdan, y esa discrepancia vale la pena reportarla a través de consumptionPercentage.
FULFILLMENT_ISSUE apunta de vuelta hacia ti
FULFILLMENT_ISSUE es el único motivo que trata en parte de tu app, no del cliente. Significa que dicen que no pudieron recibir o usar lo que pagaron. Antes de impugnar por reflejo, revisa tus registros de entrega. Si tu propio servidor muestra que el derecho nunca se activó, o que los créditos nunca se abonaron, el cliente tiene razón, y DECLINE es la preferencia equivocada. Pelear un fallo de entrega real desperdicia la ventana y puede empujar al cliente hacia su banco, donde un contracargo cuesta más de lo que habría costado el reembolso.
UNSATISFIED_WITH_PURCHASE es donde deciden las pruebas
Este es el arrepentimiento del comprador de toda la vida, y es el motivo donde tus datos de consumo hacen el mayor trabajo. El producto funcionó. El cliente usó parte o todo y ahora quiere que le devuelvan el dinero. Un consumptionPercentage alto, un deliveryStatus honesto de DELIVERED y un refundPreference de DECLINE o GRANT_PRORATED es el caso que Apple te pide que presentes. Envía los números, no un argumento.
LEGAL y OTHER
LEGAL significa que el cliente invocó un derecho legal o regulatorio. Las personas razonables discrepan, pero por regla general esta no es la ventana para litigar. Concédelo y sigue adelante. OTHER es el comodín que Apple usa cuando el motivo declarado no encaja en ninguno de los cuatro anteriores. No lleva ninguna señal por sí solo, así que trata un OTHER exactamente como tratarías una solicitud sin motivo alguno: empieza por tu estado de entrega y tus pruebas de uso.
Cómo el motivo cambia tu respuesta, campo por campo
Respondes a un CONSUMPTION_REQUEST llamando a Send Consumption Information con un cuerpo ConsumptionRequest. El motivo debería dar forma a tres campos de ese cuerpo.
customerConsented tiene que ser true
Apple solo acepta el envío cuando customerConsented es true, es decir, que el cliente aceptó compartir los datos de consumo. Si no tienes ese consentimiento, no puedes enviar datos en absoluto, sin importar el motivo. Sin consentimiento, no hay pruebas, y la solicitud se decide sin tus números.
deliveryStatus y consumptionPercentage llevan los hechos
deliveryStatus indica si entregaste una compra que funcionaba. Si es cualquier cosa distinta de DELIVERED, Apple exige que consumptionPercentage sea 0. Cuando sí entregaste, consumptionPercentage es un entero en milliunits de 0 a 100,000, donde 100,000 significa que el cliente usó la compra entera. Este par es tu núcleo factual, y es lo que debería sostener un caso de FULFILLMENT_ISSUE o de UNSATISFIED_WITH_PURCHASE, no el motivo en sí.
refundPreference es tu única palanca
refundPreference es donde declaras lo que quieres. Apple documenta tres valores: GRANT_FULL, GRANT_PRORATED y DECLINE. Lee el motivo, sopésalo frente a tus datos y luego elige. Un FULFILLMENT_ISSUE con una entrega fallida en tus registros se inclina por GRANT_FULL. Un UNSATISFIED_WITH_PURCHASE sobre un producto consumido por completo se inclina por DECLINE o GRANT_PRORATED. LEGAL se inclina por GRANT_FULL.
Lo que realmente te cuesta un reembolso
El campo del motivo importa porque un reembolso rara vez es solo la venta saliendo de tu contabilidad. Para un consumible que ya se usó, pagaste por cumplirlo. Un paquete de créditos que llamó a una API de inferencia de pago, un lote de imágenes generadas que quemó tiempo de GPU, una exportación almacenada que ocupa tu factura de almacenamiento, un pago a un creador que ya enviaste: esos costes siguen gastados cuando se revierte la compra. La tienda devuelve el dinero del cliente. No te devuelve tu cómputo.
Por eso vale la pena leer el motivo. Supón que un cliente compró 5,000 créditos que cada uno dispara una llamada a una API de pago, gastó 4,000 de ellos y luego presentó la solicitud bajo UNSATISFIED_WITH_PURCHASE. Tu deliveryStatus es DELIVERED, tu consumptionPercentage es 80,000 milliunits, y una preferencia DECLINE o GRANT_PRORATED es la diferencia entre comerte la factura de la API y recuperar la mayor parte. Ahora cambia el motivo a FULFILLMENT_ISSUE con registros que muestran que los créditos nunca se abonaron, y la jugada honesta y más barata es GRANT_FULL antes de que el cliente escale a su banco.
Leer el motivo sin reaccionar de más
La trampa es tratar el motivo como una prueba. UNINTENDED_PURCHASE no es una confesión de que el producto quedó sin usar, y LEGAL no siempre es una reclamación legal genuina. El motivo acota la situación. Tus registros de entrega y de consumo la resuelven. Cuando concuerdan con el cliente, concede pronto y barato. Cuando contradicen al cliente, esa contradicción, expresada como deliveryStatus y consumptionPercentage, es lo más fuerte que puedes enviar. RefundHalt lee consumptionRequestReason en cada CONSUMPTION_REQUEST y lo combina automáticamente con tus datos de uso reales, para que cada motivo reciba la respuesta que merece dentro de la ventana de 12 hours.
El cambio es pequeño y fácil de pasar por alto, pero movió la conversación del reembolso a tu favor. Apple ahora te dice por qué, antes de que respondas. Aprovéchalo.
Preguntas frecuentes
- ¿Qué es consumptionRequestReason?
- consumptionRequestReason es un campo de cadena que Apple incluye en cada notificación CONSUMPTION_REQUEST, añadido en la versión 2.11 de App Store Server Notifications en la WWDC24. Indica el motivo declarado por el propio cliente para solicitar el reembolso, dándote contexto antes de que respondas con datos de consumo dentro de la ventana de 12 hours.
- ¿Cuáles son los valores posibles de consumptionRequestReason?
- Hay cinco: UNINTENDED_PURCHASE, FULFILLMENT_ISSUE, UNSATISFIED_WITH_PURCHASE, LEGAL y OTHER. Apple envía exactamente uno por solicitud de reembolso. Cada uno apunta a una situación diferente, desde un toque accidental hasta un motivo legal declarado, y cada uno debería dar forma al refundPreference y a los datos de consumo que devuelves.
- ¿El motivo del reembolso decide si me quedo con el dinero?
- No. consumptionRequestReason es contexto, no un veredicto. Apple sigue decidiendo el reembolso, ponderando tu refundPreference, tu deliveryStatus y consumptionPercentage, y el historial del cliente. El motivo te dice qué caso presentar. Tus datos de entrega y de uso son lo que lo presenta.
- ¿Cuánto tiempo tengo para responder a un CONSUMPTION_REQUEST?
- Tienes 12 hours desde que recibes la notificación CONSUMPTION_REQUEST para llamar a Send Consumption Information. La llamada debe establecer customerConsented en true, o Apple la rechaza. Pierde la ventana y el reembolso se decide sin ninguno de tus datos.
- ¿Aparece consumptionRequestReason en los reembolsos de suscripciones?
- Sí. La misma actualización de la WWDC24 que añadió consumptionRequestReason también empezó a enviar CONSUMPTION_REQUEST para las suscripciones de renovación automática, no solo para los consumibles. Para la mayoría de las apps eso significa que el campo del motivo alcanza ahora los reembolsos que más importan financieramente.
Fuentes y lecturas adicionales
RefundHalt
El piloto automático de reembolsos para App Store y Google Play
Seguir leyendo
La revisión de contracargos de Google Play te da 24 horas para defenderte, esto es lo que debes enviar
Cuando un banco revierte un cargo de Google Play, Google envía a tu servidor una PendingRefundReviewNotification e inicia un reloj de 24 horas. Respóndela a través de la ReviewRefund API con una preferencia de reembolso y pruebas de consumo reales, o la disputa se decide sin ti. Aquí está todo el flujo, campo por campo.
Adjunta un appAccountToken a cada compra de la App Store, o no podrás defender el reembolso
Apple envía a tu servidor un CONSUMPTION_REQUEST cuando un cliente pide un reembolso, pero la transacción nunca dice quién es. appAccountToken es el UUID que vincula una compra con tu usuario. Configúralo y podrás responder a Apple con datos reales. Omítelo y estarás adivinando.