16 czerwca 2025 wprowadzilismy zmiany w obsłudze zasobów /payments/refunds, za pomocą których możesz zlecać zwroty płatności do kupujących oraz pobierać o nich informacje.

Udostępniliśmy wtedy nowe pola order.id i commandId i zapowiedzieliśmy, że planujemy oznaczyć je jako wymagane w grudniu 2025.

Co zmienimy?

15 grudnia 2025 pola order.id i commandId w POST /payments/refunds oznaczymy jako wymagane.

Jeśli Twoja aplikacja nie obsługuje jeszcze nowych pól, pamiętaj o wprowadzeniu niezbędnych zmian.

Co, jeśli nie dostosujesz aplikacji do zmian?

Aplikacja utraci możliwość wykonywania zwrotów płatności do kupujących. Jeśli nowe pola nie zostaną uwzględnione w strukturze requestu, zwrócimy błąd 422 Unprocessable Entity wraz z informacją o brakujących polach.

Dlaczego wprowadzamy zmianę?

Obecnie, aby korzystać z One Fulfillment, sprzedawca musi posiadać dodatkowe konto.

W przyszłości usługa ta będzie dostępna bezpośrednio na koncie sprzedawcy. Oznacza to, że pojedyncza płatność będzie mogła obejmować więcej niż jedno zamówienie – na przykład, sprzedawca otrzyma jedną wpłatę za zamówienie realizowane przez One Fulfillment (obsługiwane przez Magazyn Allegro) oraz za zamówienie obsługiwane samodzielnie. Aby ułatwić ich rozróżnienie, wprowadzamy pole order.id w obsłudze zwrotów płatności.

Pole commandId zapewni idempotentność tworzenia zwrotów. Wcześniej, jeśli aplikacja zlecała zwrot na połowę płatności i połączenie zostało przerwane, a próba zwrotu ponowiona, istniało ryzyko podwójnego wykonania zwrotu. Działo się tak, ponieważ nie znaliśmy dokładnej intencji użytkownika. Aktualnie, jeśli aplikacja w kolejnym requeście przekaże taką samą wartość dla commandId, w odpowiedzi za każdym razem zwrócimy ten sam wynik - nie utworzymy nowej dyspozycji zwrotu, jeśli wcześniejsza zakończyła się powodzeniem.