Zwrot przez Advanced Commerce API to jedyny sposób, w jaki deweloper iOS może zainicjować zwrot pieniędzy, a ostateczną decyzję i tak podejmuje Apple

Zwykli deweloperzy iOS nie mogą zwrócić klientowi pieniędzy. W czerwcu 2026 roku App Store Commerce Engineer odpowiedział na pytanie na forum deweloperów jednym zdaniem: obecnie deweloper nie ma możliwości bezpośredniego zlecenia zwrotu. Jest jeden wyjątek i kryje się w Advanced Commerce API. Aplikacje, które Apple do niego dopuści, mogą wysłać wniosek o zwrot przez Advanced Commerce API, unieważnić subskrypcję ze zwrotem pieniędzy albo poprosić o dowolną kwotę. O tym, czy pieniądze zostaną przelane, nadal decyduje Apple.

Czym jest Advanced Commerce API i kto ma do niego dostęp

Apple udostępniło Advanced Commerce API 23 stycznia 2025 roku. Obsługuje ono zakupy w aplikacji Apple dla wyjątkowo dużych katalogów niestandardowych zakupów jednorazowych, subskrypcji oraz subskrypcji z opcjonalnymi dodatkami. Nie tworzysz każdego produktu w App Store Connect. Definiujesz SKU na własnym serwerze i przesyłasz je do Apple w momencie zakupu.

Dostęp przyznawany jest osobno dla każdej aplikacji. Wypełniasz formularz wniosku, a strona Apple o kwalifikowalności wymienia trzy modele biznesowe, które muszą stanowić rdzeń aplikacji:

• Wyjątkowo duże katalogi zakupów jednorazowych, takich jak audiobooki, zajęcia, kursy czy mini aplikacje.
• Wyjątkowo duże katalogi treści subskrypcyjnych, w których oferta każdego twórcy jest osobną subskrypcją.
• Subskrypcja z opcjonalnymi dodatkami, które odnawiają się razem jako jeden zakup, na przykład kanały premium lub sport.

Apple pozwala też złożyć wniosek, gdy API wymaga inny program. Wymaga go Mini Apps Partner Program, który wypłaca członkom 85% kwalifikujących się przychodów z zakupów w aplikacji w hostowanych mini aplikacjach.

Endpointy zwrotów pojawiły się później i wymagają podpisu

Wersja 1.1 z 24 marca 2025 roku dodała Request Transaction Refund i Revoke Subscription. Strona programu Apple mówi, że aplikacje oferujące treści subskrypcyjne mogą też kwalifikować się do API Cancel, Revoke i Refund, aby obsługiwać anulowania, weryfikować treści po zakupie i zarządzać katalogami. Każda strona endpointu dodaje ten sam warunek: Twój Account Holder musi podpisać Advanced Commerce API Addendum, a jeśli najnowsza wersja nie jest zaakceptowana, wywołanie zwraca błąd. To Addendum, a nie dokumentacja, wymienia przypadki użycia, do których służy każdy endpoint.

Trzy endpointy obok siebie

Cancel a Subscription zatrzymuje kolejne obciążenie

Cancel wyłącza automatyczne odnawianie. Według Apple klient zachowuje dostęp do końca bieżącego okresu. Nic nie jest zwracane. To właściwe wywołanie, gdy klient chce zrezygnować i wykorzystał już opłacony czas.

Revoke Subscription kończy wszystko od razu

Revoke ustawia automatyczne odnawianie na false i unieważnia subskrypcję z pełnym lub proporcjonalnym zwrotem. Treść żądania zawiera refundReason, refundRiskingPreference, refundType i requestInfo. Apple wysyła następnie powiadomienie REFUND na Twój endpoint App Store Server Notifications V2. Instrukcja Apple jest konkretna: wyłącz usługę od daty revocationDate z tego powiadomienia i nie wyłączaj jej, zanim powiadomienie dotrze.

Request Transaction Refund działa pozycja po pozycji

To precyzyjne narzędzie. Wysyłasz listę pozycji, a każda zawiera SKU, refundReason, refundType i flagę revoke. Przy CUSTOM wysyłasz też refundAmount w tysięcznych częściach jednostki waluty, więc 4990 oznacza 4,99. Jeśli wyślesz kwotę z FULL lub PRORATED, Apple odrzuci ją błędem 4000155. Odpowiedź zawiera podpisaną transakcję, a w przypadku subskrypcji podpisane informacje o odnowieniu.

Apple akceptuje te wartości refundReason: UNINTENDED_PURCHASE, FULFILLMENT_ISSUE, UNSATISFIED_WITH_PURCHASE, LEGAL, OTHER i MODIFY_ITEMS_REFUND. Siódma, SIMULATE_REFUND_DECLINE, służy wyłącznie do testów w sandboxie i TestFlight. Istnieje, bo App Store może odmówić.

Apple może odrzucić nawet Twój własny wniosek o zwrot

Nazwa endpointu jest uczciwa. To wniosek. Dwa pola pokazują, gdzie naprawdę zapada decyzja.

refundRiskingPreference otwiera drogę do sprawdzenia wykorzystania

Apple opisuje refundRiskingPreference jako określenie, czy App Store poprosi Cię o dane o wykorzystaniu, aby oprzeć na nich decyzję o zwrocie. Domyślna wartość to true. Gdy jest true, otrzymujesz CONSUMPTION_REQUEST dotyczący własnego wniosku o zwrot i odpowiadasz przez Send Consumption Information. Apple prosi deweloperów o odpowiedź w ciągu 12 godzin od otrzymania CONSUMPTION_REQUEST. Ustaw false, a to powiadomienie nie przyjdzie.

Błędy, które oznaczają odmowę

Na PendingRefundError trzeba się przygotować. Prawdopodobna przyczyna to klient, który poprosił Apple przez Report a Problem, zanim zareagował Twój zespół wsparcia. Zasady kwalifikowalności Apple i tak wymagają od tych aplikacji ścieżki do zwrotu w aplikacji, czyli linku Report a Problem albo API beginRefundRequest, więc obie drogi są otwarte jednocześnie.

Ile kosztuje Cię zwrot przez Advanced Commerce API

Zwrot z własnej inicjatywy wydaje się tańszy niż spór. To jednak nadal odpływ pieniędzy, a API sprawia, że niektóre błędy łatwo powtarzać na dużą skalę.

Podatek w niestandardowej kwocie

Apple podaje, że wnioskowany refundAmount musi zawierać podatek we wszystkich regionach poza Kanadą i Stanami Zjednoczonymi. Zespół, który liczy zwrot CUSTOM od ceny SKU bez podatku, odda klientom za mało w każdym innym sklepie, a potem zapłaci czasem zespołu wsparcia za poprawienie każdego przypadku.

Koszty, które nie wracają

• Wypłaty: w katalogu twórców lub u hosta mini aplikacji udział twórcy jest często wypłacany przy sprzedaży. Zwrot dla klienta go nie odzyskuje.
• Licencje na treści: opłaty za tytuł należne właścicielowi praw do audiobooka lub kursu mogą, zależnie od umowy, powstać już przy dostępie, a zwrot ich nie cofa.
• Moc obliczeniowa: streaming, transkodowanie i cała praca serwera wykonana dla zakupu są już na Twoim rachunku.
• Wywołania API: usługi zewnętrzne rozliczane za żądanie, od mowy po inferencję modeli, pozostają rozliczone po zwrocie.

Pełny zwrot, choć chodziło o jedną pozycję

Revoke Subscription zwraca pieniądze i kończy całą subskrypcję, razem z dodatkami. Jeśli klient kwestionuje tylko jeden dodatek, Request Transaction Refund pozwala zwrócić wyłącznie to SKU, z flagą revoke ustawioną tylko dla tej pozycji. Wywołanie Revoke Subscription przy reklamacji jednej pozycji oddaje także przychód z planu podstawowego.

Lista kontrolna przed włączeniem tych funkcji

• Upewnij się, że Twój Account Holder zaakceptował aktualne Advanced Commerce API Addendum, i ustaw alert na błąd, który pojawia się, gdy akceptacja wygaśnie.
• Generuj nowy requestReferenceId w formacie UUID dla każdego żądania i używaj tego samego ponownie tylko przy ponawianiu wywołania, które przekroczyło limit czasu.
• Kolejkuj wywołania zwrotów. Limit to 5 na sekundę na aplikację, a odpowiedź 429 zawiera nagłówek Retry-After w milisekundach UNIX.
• Testuj odmowy w sandboxie z SIMULATE_REFUND_DECLINE i pamiętaj, że limity sandboxa to 10 procent limitów produkcyjnych.
• Decyduj o refundRiskingPreference w każdym przypadku osobno i miej gotowy mechanizm odpowiedzi z danymi o wykorzystaniu na 12-godzinne okno, gdy wartość pozostaje true.
• Kończ dostęp dopiero po nadejściu powiadomienia REFUND, od jego revocationDate.
• Zapisuj powód, kwotę i SKU każdego żądania, aby Twój własny wskaźnik zwrotów był widoczny, zanim zobaczy go Apple.