अगर आपने कभी Apple के refund flow पर काम किया है, तो आपने डॉक्यूमेंटेशन में 12-hour response window का ज़िक्र जरूर देखा होगा। जो बात हमेशा स्पष्ट नहीं होती, वह यह है कि असल में जवाब कैसे दिया जाए।
CONSUMPTION_REQUEST एक notification है; जवाब एक अलग API को किया गया कॉल है, जिसकी अपनी key होती है और एक body होती है जिसका आकार 2021 से दो बार बदल चुका है। हमने कुछ समय पहले नोटिफिकेशन में खुद क्या होता है इस पर बात की थी। यह उसके बाद का हिस्सा है, जब आपको वास्तव में इसका जवाब देना होता है।
मुख्य बातें
यह App Store Server API को किया गया एक PUT request है। यही पूरा तरीका है।
हर request को आपकी in-app purchase key से बने JWT के साथ sign किया जाता है; 60 मिनट से पुराने token को reject कर दिया जाता है।
v2 body में पांच फ़ील्ड होते हैं, जिनमें से तीन आवश्यक हैं।
Apple सिर्फ 202 जवाब देता है, और कुछ नहीं। refund का फैसला बाद में, एक अलग notification के रूप में आता है।
notification आने के क्षण से बारह घंटे का समय मिलता है, और आप इस विंडो के भीतर फिर से भेज सकते हैं।
Apple Consumption Request क्या है?
तकनीकी शब्दों को हटा दें तो, Apple consumption request असल में एक सवाल है। एक customer ने Apple से अपना पैसा वापस मांगा है, और जवाब देने से पहले Apple आपके server की तरफ मुड़ता है और पूछता है: क्या इस व्यक्ति को वह मिला जिसके लिए उसने पैसे दिए, और क्या उसने उसका इस्तेमाल किया?
Apple आपकी बात को उन चीज़ों के साथ मिलाता है जो वह पहले से जानता है, जैसे यह customer कितनी बार refund मांगता है, और फिर खुद फैसला लेता है।
लोग अक्सर आखिरी बात को गलत समझ लेते हैं। आप कुछ भी approve या deny नहीं करते; आप सिर्फ facts सौंपते हैं।
Apple जो CONSUMPTION_REQUEST भेजता है, वह उस server URL पर आता है जो आपने App Store Connect में डाला है, और यह एक version 2 server notification होता है।
2021 में यह केवल consumables के लिए चलता था। 2024 में subscriptions को भी इसमें जोड़ दिया गया, और दिसंबर 2025 में Apple ने endpoint का version 2 जारी किया, जिसके docs कहते हैं कि यह हर product type को कवर करता है, जिसमें non-consumables और non-renewing subscriptions भी शामिल हैं। notification reference page अभी भी केवल मूल दो को ही सूचीबद्ध करता है; मैं नए page पर भरोसा करूंगा और सभी चार के लिए तैयारी करूंगा।
और नाम की बात करें तो: लोग Apple refund API सर्च करते हैं, जबकि अलग से ऐसी कोई चीज़ है ही नहीं। यह call App Store Server API का ही हिस्सा है।
सबमिट करने से पहले आपको क्या चाहिए
इनमें से तीन चीज़ों में जल्दबाज़ी नहीं की जा सकती, इसलिए इसे अपने पहले request से पहले पढ़ें, बाद में नहीं।
पहली चीज़ है एक key, विशेष रूप से एक in-app purchase key, जो App Store Connect में Users and Access के अंदर बनाई जाती है। Apple आपको एक .p8 file ठीक एक बार देता है; आपको इसकी key ID और अपनी issuer ID भी चाहिए होगी।
दूसरी चीज़, transaction ID (जो Apple आपको देता है) से आपके डेटाबेस में मौजूद किसी व्यक्ति (जो आपको चाहिए) तक पहुंचने का कोई तरीका। इसका साफ-सुथरा तरीका है appAccountToken, जो purchase के समय सेट किया जाता है और फिर उस transaction से जुड़े हर notification में वापस आता है।
अगर यह शब्द आपके लिए नया है, तो पहले appAccountToken refund defense के लिए क्यों ज़रूरी है पढ़ें, क्योंकि इस mapping के बिना इस पोस्ट का बाकी हिस्सा सिर्फ सैद्धांतिक है।
तीसरी चीज़, और यह वह है जिसे रात 2 बजे ठीक नहीं किया जा सकता: consent।
Apple के docs साफ कहते हैं कि अगर customer ने यह data शेयर करने के लिए सहमति नहीं दी है, तो आप बिल्कुल जवाब न दें। वे यह भी कहते हैं, थोड़ी कानूनी भाषा में, कि valid consent क्या माना जाएगा यह इस पर निर्भर करता है कि आप कहां काम करते हैं, और इस पर वे सलाह नहीं दे सकते।
आपके terms में opt-in भाषा होना सामान्य तरीका है, और request आने से पहले यह मौजूद होना चाहिए।
चौथी चीज़ है खुद transaction ID, जो आपको केवल तब मिलता है जब notification आ जाए और आपने Apple का signature जांच लिया हो।
Consumption Information स्टेप-बाय-स्टेप कैसे सबमिट करें
send consumption information apple सर्च करने वाले ज़्यादातर लोग Apple के reference page पर पहुंच जाते हैं, जो फ़ील्ड सूचीबद्ध करता है और फिर अचानक रुक जाता है। यहां व्यावहारिक रूप में पूरा क्रम है।
सबसे पहले जांचें कि notification असली है। signedPayload एक JWS होता है; Apple की App Store Server Library इसे verify करती है और decoded transaction वापस देती है, जिसमें transactionId और appAccountToken शामिल होते हैं।
अपनी तरफ purchase को ढूंढें। आपको यह जानना है: क्या हमने इसे deliver किया, लगभग कितना हिस्सा इस्तेमाल हुआ है, क्या उन्होंने पहले कोई sample या trial देखा था, और हम चाहेंगे कि Apple क्या करे।
अब token की बारी। Header: alg ES256 है, kid आपकी key ID है, typ JWT है। Payload: iss आपकी issuer ID है, iat अभी का समय है, exp अधिकतम 60 मिनट बाद का है, aud शब्दशः स्ट्रिंग appstoreconnect-v1 है, और bid आपकी bundle ID है। Apple की JSON Web Tokens बनाने की गाइड में सटीक structure दिया गया है, हालांकि library यह आपके लिए खुद बना देती है।
इसे PUT करें। production URL है https://api.storekit.apple.com/inApps/v2/transactions/consumption/{transactionId}, जिसमें JWT को Authorization header में Bearer token के रूप में भेजा जाता है, और एक body कुछ इस तरह की होती है:
{
"customerConsented": true,
"deliveryStatus": "DELIVERED",
"consumptionPercentage": 94000,
"sampleContentProvided": false,
"refundPreference": "DECLINE"
}
Apple 202 Accepted जवाब देता है, और आपको इतना ही मिलता है। समय, body और transaction ID लॉग करें, क्योंकि एक महीने बाद कोई पूछेगा कि हमने Apple को इस बारे में क्या बताया था।
फिर आप इंतज़ार करते हैं। फैसला REFUND या REFUND_DECLINED notification के रूप में आता है। अगर यह REFUND है, तो उसी दिन content या entitlement हटा दें।
तो अगर आप सोच रहे थे कि how to submit consumption information Apple will actually use, तो यही है: एक request, पांच फ़ील्ड, विंडो के भीतर।
Apple आपको उन 12 घंटों के भीतर एक updated payload भेजने की भी अनुमति देता है, इसलिए अगर पहली call आधी जानकारी के साथ गई थी, तो दूसरी भेजें।
कुछ बातें जो फ़ील्ड के नाम नहीं बताते। consumptionPercentage milliunits में होता है, जिससे लोग अक्सर कन्फ्यूज़ हो जाते हैं: 94000 का मतलब है 94 प्रतिशत, 100000 का मतलब है पूरा, और यह 0 होना चाहिए अगर deliveryStatus DELIVERED के अलावा कुछ भी हो।
undelivered के विकल्प हैं UNDELIVERED_QUALITY_ISSUE, UNDELIVERED_WRONG_ITEM, UNDELIVERED_SERVER_OUTAGE और UNDELIVERED_OTHER।
refundPreference वैकल्पिक है और GRANT_FULL, GRANT_PRORATED या DECLINE में से कोई एक मान लेता है; auto-renewable subscription पर GRANT_PRORATED के लिए, percentage को छोड़ दें और Apple बाकी बचे समय से इसे खुद निकाल लेता है।
Send Consumption Information reference में पूरी error list मौजूद है।
Response Codes का मतलब क्या है
एक अच्छा response है, 202। बाकी सब Apple का यह बताना है कि आपने क्या गलत किया, अक्सर नाम लेकर।
400 वाले सबसे उपयोगी होते हैं, क्योंकि body में error का नाम दिया जाता है।
ConsumptionPercentageOutOfRangeError का मतलब लगभग हमेशा यही होता है कि किसी ने 94000 के बजाय 94 भेज दिया।
UndeliveredConsumptionPercentageNonZeroError का मतलब है कि आपने कहा कि item कभी पहुंचा ही नहीं, और फिर दावा किया कि इसका कुछ हिस्सा इस्तेमाल हुआ।
InvalidCustomerConsentedError का मतलब अपने आप स्पष्ट है।
401 token की समस्या है: गलत key, एक घंटे से ज़्यादा की expiry, एक bundle ID जो मैच नहीं करती, या एक server clock जो इतना drift कर गया हो कि iat भविष्य जैसा दिखे।
404 का मतलब है कि transaction ID नहीं मिली, और मेरा पहला सवाल हमेशा यही होता है कि क्या कोई sandbox transaction production URL पर चली गई (या इसका उल्टा)।
429 rate limit है (production में प्रति app प्रति सेकंड 50 requests, sandbox में इसका दसवां हिस्सा); फिर से try करने से पहले Retry-After header पढ़ें।
500 Apple की तरफ की समस्या है; बाद में फिर से try करें।
Sandbox में इसे कैसे टेस्ट करें
इसे टेस्ट करना सुनने में जितना लगता है उससे आसान है, बस एक बात का ध्यान रखना है।
App Store Connect में एक sandbox server URL डालें, एक sandbox Apple Account से sign in करें, कुछ खरीदें, फिर अपने app का refund sheet (beginRefundRequest) खोलें और request सबमिट करें।
Apple की refund requests के लिए testing guide बताती है कि test environment कैसे काम करता है: कोई भी reason चुनें और refund automatically approve हो जाता है; Other चुनें और DECLINE टाइप करें तो वह decline हो जाता है; prorated refund के लिए GRANT_PRORATED टाइप करें।
ध्यान देने वाली बात इन्हीं नियमों में है: sandbox उस पर फैसला करता है जो आपने sheet में टाइप किया, न कि उस पर जो आपके server ने भेजा, इसलिए यह आपको नहीं बता सकता कि आपका data Apple को किसी भी बात के लिए मनाता है या नहीं।
यह जो टेस्ट कर सकता है वह है internal plumbing: notification आता है, api.storekit-sandbox.apple.com पर आपका PUT 202 के साथ वापस आता है, और जब REFUND या REFUND_DECLINED आता है तो उसे handle किया जाता है।
साथ ही, sandbox refund emails नहीं भेजता, तो इसका इंतज़ार न करें।
Apple Refund Automation: इसे हाथ से करना कब बंद करें
हाथ से किया जाए तो, यह काम किसी के हर समय alert पर नज़र रखने, query चलाने और 12 घंटे की deadline खत्म होने से पहले पांच फ़ील्ड भेजने जैसा है।
महीने में कुछ ही Apple refund requests हों तो यह ठीक है। लेकिन उस पहले लंबे weekend पर यह बिल्कुल ठीक नहीं रहता जब कोई चेक नहीं कर रहा होता।
Apple refund requests को automate करने के लिए आप ऊपर बताई गई हर चीज़ लेते हैं और बीच से व्यक्ति को हटा देते हैं: notification आता है, आपके rules delivery और usage data को एक payload में बदलते हैं, call मिनटों में चली जाती है, फैसला case के खिलाफ लॉग हो जाता है, और एक REFUND revoke को ट्रिगर करता है।
इसे बनाना कोई बड़ा प्रोजेक्ट नहीं है; बाद में Apple के बदलावों के साथ तालमेल बनाए रखना (जैसे V1-to-v2 switch) वह हिस्सा है जो चुपचाप लागत बढ़ाता रहता है।
अगर आप यह नहीं करना चाहते, तो हमने इसके लिए बनी services पर Apple refund management tools की हमारी तुलना में चर्चा की है, जिसमें यह भी शामिल है कि Refund Sensor कहां फिट होता है और कहां नहीं।
जब भी यह बात आती है तो एक चीज़ पर मैं असहमति जताता हूं: Apple refund automation यह बदलता है कि आप कितनी भरोसेमंद तरीके से जवाब देते हैं, न कि यह कि फैसला कौन लेता है। इस API में कुछ भी किसी developer को आखिरी शब्द नहीं देता।
निष्कर्ष
call खुद छोटी है: एक signed token, एक PUT, पांच फ़ील्ड, और लॉग करने के लिए एक 202।
इसे बना या बिगाड़ने वाली चीज़ें कहीं और होती हैं: आपके terms में पहले से मौजूद consent, हर purchase पर एक appAccountToken, usage records जिन्हें आप सेकंडों में निकाल सकें, और कुछ ऐसा जो रात 3 बजे उठे जब notification आए।
इन्हें ठीक कर लें, तो यह भागदौड़ बनना बंद हो जाता है और एक ऐसी चीज़ बन जाता है जो आपका server बस खुद कर लेता है।
अक्सर पूछे जाने वाले प्रश्न
यह एक App Store Server API endpoint है जिसका उपयोग CONSUMPTION_REQUEST का जवाब देने के लिए किया जाता है। आप consumption details के साथ एक PUT request भेजते हैं, और Apple 202 Accepted रिटर्न करता है।
CONSUMPTION_REQUEST आने के बाद आपके पास 12 घंटे होते हैं। Apple इसी 12 घंटे की विंडो के भीतर एक updated payload सबमिट करने की अनुमति देता है।
हां। Apple आपको 12 घंटे की विंडो के भीतर एक updated payload भेजने की अनुमति देता है। यह तब उपयोगी होता है जब पहला submission अधूरा था।
नहीं। 202 Accepted का मतलब सिर्फ यह है कि Apple को आपकी जानकारी मिल गई। नतीजा बाद में REFUND या REFUND_DECLINED notification के रूप में आता है।
हां। consumption information सबमिट करते समय customerConsented फ़ील्ड आवश्यक है। अगर customer ने सहमति नहीं दी है, तो Apple के documentation के अनुसार जवाब न दें।
