Wprowadzamy 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.

Co zmieniliśmy?

Dla POST /payments/refunds dodaliśmy nowe pola, które możesz przekazać w żądaniu:

• commandId - unikalny identyfikator w formacie UUID, który zapewnia idempotentność tworzenia zwrotów. Wartość wygenerujesz we własnym zakresie.
• order.id - numer zamówienia, musi być powiązany z płatnością, której zlecasz zwrot. Pole zwrócimy również w odpowiedzi.

Pola aktualnie są opcjonalne, jednak w grudniu 2025 planujemy oznaczyć je jako wymagane. O dokładnej dacie poinformujemy z odpowiednim wyprzedzeniem.

Dla GET /payments/refunds dodaliśmy nowy parametr wyszukiwania order.id oraz dodatkowe pole o tej samej nazwie, które zawiera informację o numerze zamówienia powiązanym z danym zwrotem płatności.

Więcej o zarządzaniu zwrotami płatności przeczytasz w naszym poradniku.

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.