Przejdź do treści

Zwroty

GET /order/customer-returns

Allegro + rozszerzeniaallegro:api:orders:readlimit: readBETA (Allegro)

Zwroty zamówień allee.pl. Zasób BETA jak w Allegro: Accept: application/vnd.allegro.beta.v1+json (przyjmujemy też typ public). E-mail kupującego tylko z zakresem allee:api:orders:pii.

Zamówieniami allee.pl sprzedawcy obsługuje jedna integracja naraz (wybór w panelu sprzedaży → Integracje); inna aplikacja dostaje 403 ORDERS_OWNED_BY_OTHER_INTEGRATION (details.owner: PANEL, OTHER_APP, BASELINKER).

Zgodność: zgodna z Allegro REST API, z rozszerzeniami allee (pola allee.*, alleeId) — GET /order/customer-returns (BETA).
Uprawnienie: zakres allegro:api:orders:read.
Grupa limitu: read.

Parametry zapytania

offset integer

Ile pozycji pominąć.

limit integer

Ile pozycji zwrócić (1–100, domyślnie 50).

createdAt.gte string · date-time

Od.

createdAt.lte string · date-time

Do.

status string

Status.

Wartości: CREATED, IN_TRANSIT, DELIVERED, FINISHED, REJECTED, COMMISSION_REFUND_CLAIMED, COMMISSION_REFUNDED
orderId string · uuid

Zamówienie.

Odpowiedzi

200 Zwroty. · CustomerReturnList
customerReturns array<CustomerReturn> zawsze
Pola obiektu
id string zawsze

Numer zwrotu ZW-…

createdAt string · date-time zawsze
referenceNumber string zawsze
orderId string zawsze

checkoutForm.id

buyer object zawsze
Pola obiektu
login string · null zawsze
email string · null zawsze

Tylko z zakresem allee:api:orders:pii.

items array<object> zawsze
Pola obiektu
offerId string · null zawsze
quantity integer zawsze
name string zawsze
price Money zawsze

Kwota (kształt Allegro).

Pola obiektu
amount string zawsze

Kwota z dwoma miejscami po przecinku, kropka dziesiętna.

currency string zawsze

Waluta (allee.pl: tylko PLN).

Wartości: PLN
reason object zawsze
Pola obiektu
type string · null zawsze
Wartości: PARCEL_NOT_COLLECTED, null
userComment string · null zawsze
parcels array<object> zawsze
Pola obiektu
createdAt string · date-time · null zawsze
waybill string zawsze
transportingWaybill string zawsze
carrierId string · null zawsze
transportingCarrierId string · null zawsze
marketplaceId string zawsze
Wartości: allee-pl
status string zawsze
Wartości: CREATED, IN_TRANSIT, DELIVERED, FINISHED, REJECTED, COMMISSION_REFUND_CLAIMED, COMMISSION_REFUNDED
refund object · null zawsze
Pola obiektu
value Money zawsze

Zadeklarowany zwrot pieniędzy.

Pola obiektu
amount string zawsze

Kwota z dwoma miejscami po przecinku, kropka dziesiętna.

currency string zawsze

Waluta (allee.pl: tylko PLN).

Wartości: PLN
rejection object · null zawsze
Pola obiektu
reason string · null zawsze
count integer zawsze
totalCount integer zawsze

Błędy

HTTPKodZnaczenie
400VALIDATION_ERRORZła wartość parametru zapytania (400) albo pola treści (422); path wskazuje miejsce.
401invalid_tokenBrak, zły, wygasły albo odwołany token lub klucz (format OAuth, nagłówek WWW-Authenticate).
403ACCOUNT_INACTIVEKonto sprzedawcy jest nieaktywne.
403AccessDeniedBrak zakresu albo zasób innego sprzedawcy.
403KEY_QUARANTINEDKwarantanna: działa tylko odczyt (wykryto nietypowe użycie).
403KEY_SUSPENDEDKlucz albo dostęp aplikacji wstrzymany (przez sprzedawcę albo ochronę).
403ORDERS_OWNED_BY_OTHER_INTEGRATIONZamówienia sprzedawcy obsługuje inna integracja (details.owner).
429TOO_MANY_REQUESTSPrzekroczony limit (minutowy, grupy operacji albo IP).
500INTERNAL_ERRORBłąd serwera allee.
503SERVICE_UNAVAILABLEModuł chwilowo niedostępny.
Przykład
curl -sS -X GET "${ALLEE_API_URL:-https://api.allee.pl}/order/customer-returns?limit=50" \
  -H "Authorization: Bearer $ALLEE_API_KEY" \
  -H "Accept: application/vnd.allegro.beta.v1+json" \
  -w '\nHTTP %{http_code}\n'
Odpowiedź (środowisko testowe)
HTTP 200 application/vnd.allegro.beta.v1+json
{
  "customerReturns": [
    {
      "id": "ZW-900000001",
      "createdAt": "2026-11-10T11:10:05.511Z",
      "referenceNumber": "ZW-900000001",
      "orderId": "432810d0-4d26-4f39-ba5f-b89def4d4f92",
      "buyer": {
        "login": "kupujacy_demo_4816f227",
        "email": "[email protected]"
      },
      "items": [
        {
          "offerId": "900000000000021",
          "quantity": 2,
          "name": "Podróż na Księżyc DVD wydanie kolekcjonerskie",
          "price": {
            "amount": "42.90",
            "currency": "PLN"
          },
          "reason": {
            "type": null,
            "userComment": "Nie spełnia oczekiwań — Zwrot testowy z symulatora sandboxu."
          }
        }
      ],
      "parcels": [],
      "marketplaceId": "allee-pl",
      "status": "CREATED",
      "refund": null,
      "rejection": null
    }
  ],
  "count": 1,
  "totalCount": 1
}

Zwrot

GET /order/customer-returns/{customerReturnId}

zgodna z Allegroallegro:api:orders:readlimit: readBETA (Allegro)

Jeden zwrot. Cudzy i nieistniejący → 404.

Zgodność: zgodna z Allegro REST API (ten sam kształt) — GET /order/customer-returns/{customerReturnId} (BETA).
Uprawnienie: zakres allegro:api:orders:read.
Grupa limitu: read.

Parametry ścieżki

customerReturnId string wymagany

Numer zwrotu ZW-…

Odpowiedzi

200 Zwrot. · CustomerReturn
id string zawsze

Numer zwrotu ZW-…

createdAt string · date-time zawsze
referenceNumber string zawsze
orderId string zawsze

checkoutForm.id

buyer object zawsze
Pola obiektu
login string · null zawsze
email string · null zawsze

Tylko z zakresem allee:api:orders:pii.

items array<object> zawsze
Pola obiektu
offerId string · null zawsze
quantity integer zawsze
name string zawsze
price Money zawsze

Kwota (kształt Allegro).

Pola obiektu
amount string zawsze

Kwota z dwoma miejscami po przecinku, kropka dziesiętna.

currency string zawsze

Waluta (allee.pl: tylko PLN).

Wartości: PLN
reason object zawsze
Pola obiektu
type string · null zawsze
Wartości: PARCEL_NOT_COLLECTED, null
userComment string · null zawsze
parcels array<object> zawsze
Pola obiektu
createdAt string · date-time · null zawsze
waybill string zawsze
transportingWaybill string zawsze
carrierId string · null zawsze
transportingCarrierId string · null zawsze
marketplaceId string zawsze
Wartości: allee-pl
status string zawsze
Wartości: CREATED, IN_TRANSIT, DELIVERED, FINISHED, REJECTED, COMMISSION_REFUND_CLAIMED, COMMISSION_REFUNDED
refund object · null zawsze
Pola obiektu
value Money zawsze

Zadeklarowany zwrot pieniędzy.

Pola obiektu
amount string zawsze

Kwota z dwoma miejscami po przecinku, kropka dziesiętna.

currency string zawsze

Waluta (allee.pl: tylko PLN).

Wartości: PLN
rejection object · null zawsze
Pola obiektu
reason string · null zawsze

Błędy

HTTPKodZnaczenie
401invalid_tokenBrak, zły, wygasły albo odwołany token lub klucz (format OAuth, nagłówek WWW-Authenticate).
403ACCOUNT_INACTIVEKonto sprzedawcy jest nieaktywne.
403AccessDeniedBrak zakresu albo zasób innego sprzedawcy.
403KEY_QUARANTINEDKwarantanna: działa tylko odczyt (wykryto nietypowe użycie).
403KEY_SUSPENDEDKlucz albo dostęp aplikacji wstrzymany (przez sprzedawcę albo ochronę).
404NOT_FOUNDNie ma takiego zasobu (albo należy do innego sprzedawcy — dla wątków, zwrotów i spraw odpowiedź jest ta sama).
429TOO_MANY_REQUESTSPrzekroczony limit (minutowy, grupy operacji albo IP).
500INTERNAL_ERRORBłąd serwera allee.
Przykład
curl -sS -X GET "${ALLEE_API_URL:-https://api.allee.pl}/order/customer-returns/ZW-900000001" \
  -H "Authorization: Bearer $ALLEE_API_KEY" \
  -H "Accept: application/vnd.allegro.beta.v1+json" \
  -w '\nHTTP %{http_code}\n'
Odpowiedź (środowisko testowe)
HTTP 200 application/vnd.allegro.beta.v1+json
{
  "id": "ZW-900000001",
  "createdAt": "2026-11-10T11:10:05.511Z",
  "referenceNumber": "ZW-900000001",
  "orderId": "432810d0-4d26-4f39-ba5f-b89def4d4f92",
  "buyer": {
    "login": "kupujacy_demo_4816f227",
    "email": "[email protected]"
  },
  "items": [
    {
      "offerId": "900000000000021",
      "quantity": 2,
      "name": "Podróż na Księżyc DVD wydanie kolekcjonerskie",
      "price": {
        "amount": "42.90",
        "currency": "PLN"
      },
      "reason": {
        "type": null,
        "userComment": "Nie spełnia oczekiwań — Zwrot testowy z symulatora sandboxu."
      }
    }
  ],
  "parcels": [],
  "marketplaceId": "allee-pl",
  "status": "CREATED",
  "refund": null,
  "rejection": null
}

Zwrot dotarł / deklaracja zwrotu pieniędzy

PUT /order/customer-returns/{customerReturnId}

tylko alleeallegro:api:orders:writelimit: writeBETA (Allegro)

{"status": "DELIVERED"} = paczka zwrotna dotarła. {"allee": {"refund": {"value": {...}}}} = deklaracja zwrotu pieniędzy (kończy zwrot — allee nie przenosi pieniędzy; kwota 0,01 zł … produkty + dostawa). Oba pola naraz: najpierw DELIVERED, potem zakończenie.

Zgodność: tylko allee — Rozszerzenie allee (Allegro: /payments/refunds).
Uprawnienie: zakres allegro:api:orders:write.
Grupa limitu: write.

Parametry ścieżki

customerReturnId string wymagany

Numer zwrotu ZW-…

Treść żądania application/vnd.allegro.beta.v1+json

status string

Paczka zwrotna dotarła.

Wartości: DELIVERED
allee object

Deklaracja zwrotu pieniędzy (kończy zwrot; allee nie przenosi pieniędzy).

Pola obiektu
refund object wymagane
Pola obiektu
value MoneyInput wymagane

Kwota w żądaniu.

Pola obiektu
amount string|number wymagane

Kwota jako tekst „123.45” (zalecane) albo liczba.

currency string

Waluta: tylko PLN (domyślnie PLN).

Wartości: PLN

Odpowiedzi

200 Zwrot po zmianie. · CustomerReturn
id string zawsze

Numer zwrotu ZW-…

createdAt string · date-time zawsze
referenceNumber string zawsze
orderId string zawsze

checkoutForm.id

buyer object zawsze
Pola obiektu
login string · null zawsze
email string · null zawsze

Tylko z zakresem allee:api:orders:pii.

items array<object> zawsze
Pola obiektu
offerId string · null zawsze
quantity integer zawsze
name string zawsze
price Money zawsze

Kwota (kształt Allegro).

Pola obiektu
amount string zawsze

Kwota z dwoma miejscami po przecinku, kropka dziesiętna.

currency string zawsze

Waluta (allee.pl: tylko PLN).

Wartości: PLN
reason object zawsze
Pola obiektu
type string · null zawsze
Wartości: PARCEL_NOT_COLLECTED, null
userComment string · null zawsze
parcels array<object> zawsze
Pola obiektu
createdAt string · date-time · null zawsze
waybill string zawsze
transportingWaybill string zawsze
carrierId string · null zawsze
transportingCarrierId string · null zawsze
marketplaceId string zawsze
Wartości: allee-pl
status string zawsze
Wartości: CREATED, IN_TRANSIT, DELIVERED, FINISHED, REJECTED, COMMISSION_REFUND_CLAIMED, COMMISSION_REFUNDED
refund object · null zawsze
Pola obiektu
value Money zawsze

Zadeklarowany zwrot pieniędzy.

Pola obiektu
amount string zawsze

Kwota z dwoma miejscami po przecinku, kropka dziesiętna.

currency string zawsze

Waluta (allee.pl: tylko PLN).

Wartości: PLN
rejection object · null zawsze
Pola obiektu
reason string · null zawsze

Błędy

HTTPKodZnaczenie
401invalid_tokenBrak, zły, wygasły albo odwołany token lub klucz (format OAuth, nagłówek WWW-Authenticate).
403ACCOUNT_INACTIVEKonto sprzedawcy jest nieaktywne.
403AccessDeniedBrak zakresu albo zasób innego sprzedawcy.
403KEY_QUARANTINEDKwarantanna: działa tylko odczyt (wykryto nietypowe użycie).
403KEY_SUSPENDEDKlucz albo dostęp aplikacji wstrzymany (przez sprzedawcę albo ochronę).
404NOT_FOUNDNie ma takiego zasobu (albo należy do innego sprzedawcy — dla wątków, zwrotów i spraw odpowiedź jest ta sama).
409CUSTOMER_RETURN_ALREADY_FINISHEDZwrot już zakończony.
409INVALID_STATUS_TRANSITIONPrzejście statusu niedozwolone (details.current = bieżący).
413PAYLOAD_TOO_LARGETreść żądania za duża (JSON 5 MB, faktura PDF 3 MB).
415UNSUPPORTED_MEDIA_TYPEZły Content-Type treści.
422JsonMappingExceptionTreść nie jest poprawnym JSON albo ma zły kształt (np. images jako obiekty).
422UnknownJSONPropertyPole nieznane w tym miejscu (path wskazuje które).
422VALIDATION_ERRORZła wartość parametru zapytania (400) albo pola treści (422); path wskazuje miejsce.
429TOO_MANY_REQUESTSPrzekroczony limit (minutowy, grupy operacji albo IP).
500INTERNAL_ERRORBłąd serwera allee.
Przykład
curl -sS -X PUT "${ALLEE_API_URL:-https://api.allee.pl}/order/customer-returns/ZW-900000001" \
  -H "Authorization: Bearer $ALLEE_API_KEY" \
  -H "Accept: application/vnd.allegro.beta.v1+json" \
  -H "Content-Type: application/vnd.allegro.public.v1+json" \
  --data-binary @- \
  -w '\nHTTP %{http_code}\n' <<'JSON'
{
  "status": "DELIVERED",
  "allee": {
    "refund": {
      "value": {
        "amount": "89.80",
        "currency": "PLN"
      }
    }
  }
}
JSON
Odpowiedź (środowisko testowe)
HTTP 200 application/vnd.allegro.beta.v1+json
{
  "id": "ZW-900000001",
  "createdAt": "2026-11-10T11:10:05.511Z",
  "referenceNumber": "ZW-900000001",
  "orderId": "432810d0-4d26-4f39-ba5f-b89def4d4f92",
  "buyer": {
    "login": "kupujacy_demo_4816f227",
    "email": "[email protected]"
  },
  "items": [
    {
      "offerId": "900000000000021",
      "quantity": 2,
      "name": "Podróż na Księżyc DVD wydanie kolekcjonerskie",
      "price": {
        "amount": "42.90",
        "currency": "PLN"
      },
      "reason": {
        "type": null,
        "userComment": "Nie spełnia oczekiwań — Zwrot testowy z symulatora sandboxu."
      }
    }
  ],
  "parcels": [],
  "marketplaceId": "allee-pl",
  "status": "FINISHED",
  "refund": {
    "value": {
      "amount": "89.80",
      "currency": "PLN"
    }
  },
  "rejection": null
}

Odrzucenie zwrotu

POST /order/customer-returns/{customerReturnId}/rejection

zgodna z Allegroallegro:api:orders:writelimit: writeBETA (Allegro)

Kupujący widzi status „Odrzucony” i uzasadnienie. Ponowne odrzucenie → 409.

Zgodność: zgodna z Allegro REST API (ten sam kształt) — POST /order/customer-returns/{customerReturnId}/rejection (BETA).
Uprawnienie: zakres allegro:api:orders:write.
Grupa limitu: write.

Parametry ścieżki

customerReturnId string wymagany

Numer zwrotu ZW-…

Nagłówki

Idempotency-Key string

Ochrona przed podwójnym wykonaniem (jak Stripe/Amazon): powtórzony POST z tym samym kluczem i tą samą treścią w ciągu 24 h zwraca zapisaną odpowiedź z nagłówkiem Idempotent-Replayed: true i niczego nie wykonuje drugi raz. Inna treść → 422 IDEMPOTENCY_KEY_REUSED; żądanie jeszcze trwa → 409 IDEMPOTENCY_KEY_IN_USE. 1–100 znaków ASCII (np. UUID).

Treść żądania application/vnd.allegro.beta.v1+json

rejection object wymagane
Pola obiektu
code string
Wartości: REFUND_REJECTED
reason string wymagane

Uzasadnienie dla kupującego (do 500 znaków, bez linków).

Odpowiedzi

200 Odrzucono. · CustomerReturn
id string zawsze

Numer zwrotu ZW-…

createdAt string · date-time zawsze
referenceNumber string zawsze
orderId string zawsze

checkoutForm.id

buyer object zawsze
Pola obiektu
login string · null zawsze
email string · null zawsze

Tylko z zakresem allee:api:orders:pii.

items array<object> zawsze
Pola obiektu
offerId string · null zawsze
quantity integer zawsze
name string zawsze
price Money zawsze

Kwota (kształt Allegro).

Pola obiektu
amount string zawsze

Kwota z dwoma miejscami po przecinku, kropka dziesiętna.

currency string zawsze

Waluta (allee.pl: tylko PLN).

Wartości: PLN
reason object zawsze
Pola obiektu
type string · null zawsze
Wartości: PARCEL_NOT_COLLECTED, null
userComment string · null zawsze
parcels array<object> zawsze
Pola obiektu
createdAt string · date-time · null zawsze
waybill string zawsze
transportingWaybill string zawsze
carrierId string · null zawsze
transportingCarrierId string · null zawsze
marketplaceId string zawsze
Wartości: allee-pl
status string zawsze
Wartości: CREATED, IN_TRANSIT, DELIVERED, FINISHED, REJECTED, COMMISSION_REFUND_CLAIMED, COMMISSION_REFUNDED
refund object · null zawsze
Pola obiektu
value Money zawsze

Zadeklarowany zwrot pieniędzy.

Pola obiektu
amount string zawsze

Kwota z dwoma miejscami po przecinku, kropka dziesiętna.

currency string zawsze

Waluta (allee.pl: tylko PLN).

Wartości: PLN
rejection object · null zawsze
Pola obiektu
reason string · null zawsze

Błędy

HTTPKodZnaczenie
401invalid_tokenBrak, zły, wygasły albo odwołany token lub klucz (format OAuth, nagłówek WWW-Authenticate).
403ACCOUNT_INACTIVEKonto sprzedawcy jest nieaktywne.
403AccessDeniedBrak zakresu albo zasób innego sprzedawcy.
403KEY_QUARANTINEDKwarantanna: działa tylko odczyt (wykryto nietypowe użycie).
403KEY_SUSPENDEDKlucz albo dostęp aplikacji wstrzymany (przez sprzedawcę albo ochronę).
404NOT_FOUNDNie ma takiego zasobu (albo należy do innego sprzedawcy — dla wątków, zwrotów i spraw odpowiedź jest ta sama).
409CUSTOMER_RETURN_ALREADY_REJECTEDZwrot już odrzucony.
409INVALID_STATUS_TRANSITIONPrzejście statusu niedozwolone (details.current = bieżący).
413PAYLOAD_TOO_LARGETreść żądania za duża (JSON 5 MB, faktura PDF 3 MB).
415UNSUPPORTED_MEDIA_TYPEZły Content-Type treści.
422CARD_DATATreść wygląda na dane karty płatniczej.
422ConstraintViolationException.MissingRequiredParametersBrak wymaganego parametru lub pola (details = id parametru).
422EXTERNAL_LINKTreść zawiera link spoza allee.pl.
422JsonMappingExceptionTreść nie jest poprawnym JSON albo ma zły kształt (np. images jako obiekty).
422PROFANITYWulgaryzmy.
422SENSITIVE_REQUESTProśba o dane wrażliwe (hasła, dane logowania).
422TEXT_EMPTYPusta treść.
422TEXT_INVALIDTreść niedozwolona przez filtr.
422TEXT_TOO_LONGTreść za długa.
422VALIDATION_ERRORZła wartość parametru zapytania (400) albo pola treści (422); path wskazuje miejsce.
429TOO_MANY_REQUESTSPrzekroczony limit (minutowy, grupy operacji albo IP).
500INTERNAL_ERRORBłąd serwera allee.
Przykład
curl -sS -X POST "${ALLEE_API_URL:-https://api.allee.pl}/order/customer-returns/ZW-900000002/rejection" \
  -H "Authorization: Bearer $ALLEE_API_KEY" \
  -H "Accept: application/vnd.allegro.beta.v1+json" \
  -H "Content-Type: application/vnd.allegro.public.v1+json" \
  --data-binary @- \
  -w '\nHTTP %{http_code}\n' <<'JSON'
{
  "rejection": {
    "code": "REFUND_REJECTED",
    "reason": "Odesłany produkt nosi ślady używania — zwrot pieniędzy pomniejszony zgodnie z regulaminem."
  }
}
JSON
Odpowiedź (środowisko testowe)
HTTP 200 application/vnd.allegro.beta.v1+json
{
  "id": "ZW-900000002",
  "createdAt": "2026-11-10T11:10:05.537Z",
  "referenceNumber": "ZW-900000002",
  "orderId": "718ce396-4940-431f-815e-7a51875c71df",
  "buyer": {
    "login": "kupujacy_demo_4816f227",
    "email": "[email protected]"
  },
  "items": [
    {
      "offerId": "900000000000001",
      "quantity": 1,
      "name": "Produkt demo 01 – Projekty wnętrz",
      "price": {
        "amount": "19.99",
        "currency": "PLN"
      },
      "reason": {
        "type": null,
        "userComment": "Inny wariant niż zamówiony — Zwrot testowy z symulatora sandboxu."
      }
    }
  ],
  "parcels": [],
  "marketplaceId": "allee-pl",
  "status": "REJECTED",
  "refund": null,
  "rejection": {
    "reason": "Odesłany produkt nosi ślady używania — zwrot pieniędzy pomniejszony zgodnie z regulaminem."
  }
}