[NEWS] Zwroty płatności - 15 grudnia 2025 pola order.id i commandId oznaczymy jako wymagane / Payment refunds to buyers - on December 15, 2025, we will mark order.id and commandId fields as required

[16 czerwca 2025 wprowadzilismy zmiany](https://developer.allegro.pl/news/zwroty-platnosci-do-kupujacych-wprowadzamy-obsluge-nowych-pol-b2mRL9zG2u6) w obsłudze zasobów [/payments/refunds](https://developer.allegro.pl/tutorials/jak-obslugiwac-zamowienia-GRaj0qyvwtR#zwroty-platnosci), 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](https://developer.allegro.pl/documentation#tag/Payments/operation/initiateRefund) 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](https://allegro.pl/kampania/fulfillment), sprzedawca musi posiadać dodatkowe konto.

W przyszłości [usługa ta będzie dostępna bezpośrednio na koncie sprzedawcy](https://developer.allegro.pl/news/one-fulfillment-wkrotce-skorzystasz-z-uslugi-w-ramach-jednego-istniejacego-konta-nna7E4Wryhw). 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.

-----

[On June 16, 2025, we introduced changes](https://developer.allegro.pl/news/zwroty-platnosci-do-kupujacych-wprowadzamy-obsluge-nowych-pol-b2mRL9zG2u6) to the handling of the [/payments/refunds](https://developer.allegro.pl/tutorials/process-orders-PgPMlWDr8Cv#payment-refunds) resources, which you can use to initiate payment refunds to buyers and retrieve information about them.

We made the new **order.id** and **commandId** fields available at that time and announced that we planned to mark them as required in December 2025**.**

**What are we changing?**

**On December 15, 2025**, we will mark the order.id and commandId fields in [POST /payments/refunds](https://developer.allegro.pl/documentation#tag/Payments/operation/initiateRefund) as **required**.

If your application does not yet support the new fields, remember to make the necessary changes.

**What if you don't adapt the application to the changes?**

Your application will lose the ability to initiate payment refunds to buyers. If the new fields are not included in the request body, we will return a 422 Unprocessable Entity error with information about the missing fields.

**Why are we introducing this change?**

Currently, to use [One Fulfillment](https://allegro.pl/campaign/fulfillment), sellers must have an additional account. In the future, this [service will be available directly within the seller's main account](https://developer.allegro.pl/news/one-fulfillment-wkrotce-skorzystasz-z-uslugi-w-ramach-jednego-istniejacego-konta-nna7E4Wryhw). This means a single payment may cover more than one order – for example, a seller might receive one payment for an order fulfilled via One Fulfillment (handled by Allegro's warehouse) and for an order they fulfilled independently. To facilitate distinguishing between these, we are introducing the **order.id** field in payment refund handling.

The **commandId** field will ensure idempotency for creating refunds. Previously, if an application initiated a partial payment refund and the connection was interrupted, then the refund attempt was retried, there was a risk of the refund being processed twice. This occurred because we didn't know the exact intent of the user. Now, if the application provides the same **commandId** value in a subsequent request, we will return the same result every time – we won't create a new refund if the previous one was successful.