[NEWS] Zarządzanie zamówieniami - wprowadzamy zmiany dla zamówień, które będą eksportowane na Ukrainę metodą dostawy Allegro One / Order management - we are introducing changes for orders to be exported to Ukraine using the Allegro One delivery method

Od **25 maja 2026** udostępnimy nowe metody dostawy obsługiwane przez Allegro One w Polsce dedykowane na eksport do Ukrainy, co wiąże się z obsługą celną. Aby ułatwić wysyłkę takich zamówień poza Unię Europejską i obsłużyć takie zamówienia, będziemy wspierać zaproszonych do programu sprzedających w sprawach formalnych. Wprowadzone zmiany będą po to, by uzyskać dane, które pozwolą naszej agencji celnej One Customs reprezentować sprzedających przed organami celno-skarbowymi, dlatego m.in.:
- zablokujemy możliwość generowania etykiety transportowej do momentu, gdy sprzedający doda fakturę do zamówienia,
- będziemy weryfikować zgodność faktury z danymi w zamówieniu, w celu uniknięcia komplikacji podczas odprawy celnej.

Zmiany te obejmą również API - wprowadzimy nowe pola i zasoby, które pomogą w weryfikacji i identyfikacji faktur oraz umożliwią przekazywanie numerów seryjnych dla przesyłek eksportowanych na Ukrainę.

### Kto może skorzystać z opcji eksportu?

Sprzedający musi spełnić następujące warunki:

- **spełniać kryteria uczestnictwa** w programie i uzyskać do niego **zaproszenie**,

- wysyłać z lokalizacji **w zasięgu kuriera Allegro One**,

- mieć  **zweryfikowane konto firmowe** z aktywacją sprzedaży,

- uzupełnić **numer EORI** [w ustawieniach konta](https://salescenter.allegro.com/account/data) (uzyskanie numeru EORI: ),

- udzielić  **pełnomocnictwa dla One Customs** do reprezentowania firmy sprzedającego przed organami celno-skarbowymi.

### Kiedy oferta będzie zakwalifikowana do eksportu do Ukrainy?

- cennik dostawy musi zawierać metodę **Allegro International Ukraina**:

- Allegro International Kurier Ukraina - 01f111ce-18a4-4a90-bf00-f999d9b97ac7 
- Allegro International Odbiór w Punkcie Ukraina - 085a666f-7114-4063-9371-f999d9b97ac7
- Allegro International Automaty Paczkowe Ukraina - 0cb89f04-2203-45c7-b621-f999d9b97ac7

- ma uzupełnione **parametry**:

- **kod taryfy celnej (numer HS)** dla każdego produktu, id: 250792 - minimum 8-cyfrowy kod CN (Combined Nomenclature) albo 10 i 12-znakowe kody zawierające rozszerzenie TARIC,
- **waga produktu z opakowaniem jednostkowym**, id: 17448,

- format **Kup Teraz**,

- oferta **nie jest zestawem produktowym**.

### Co zmieniliśmy?

1. **Weryfikacja i identyfikacja faktur**:

- w zasobie do tworzenia obiektu faktury [POST /order/checkout-forms/{id}/invoices](https://developer.allegro.pl/documentation/#operation/addOrderInvoicesMetadata) pole **"invoiceNumber"** staje się **wymagane** podczas dodawania faktury w przypadku eksportu na Ukrainę metodą dostawy Allegro One.

- dla zasobu do pobierania szczegółów faktur [GET /order/checkout-forms/{id}/invoices](https://developer.allegro.pl/documentation#operation/getOrderInvoicesDetails): 

- dodaliśmy pole **"orderMode"**, które wskazuje tryb zamówienia: **REGULAR** lub **UKRAINE_EXPORT**,
- wprowadziliśmy nową strukturę **"verification"**, która umożliwia weryfikację faktury w kontekście eksportu i zawiera status oraz szczegóły weryfikacji. 

**Przykładowy response z nową strukturą odpowiedzi (fragment):** 

```
{
"orderMode": "REGULAR", // możliwe wartości: REGULAR, UKRAINE_EXPORT
"invoices": [
{
// ...
"file": {
// ...
"verification": {
"status": "ACCEPTED_WITH_WARNINGS", // możliwe wartości - ACCEPTED, ACCEPTED_WITH_WARNINGS, REJECTED (potencjalnie w przyszłości), WAITING
"details": [ // szczegóły {
"type": "WARNING", // typ informacji (WARNING lub ERROR)
"code": "MISSING_EORI_NUMBER", // dostępne wartości NOT_VERIFIED_EORI, HSN_REQUIRED, INVALID_HSN, FORBIDDEN_HSN, WEIGHT_WITH_INDIVIDUAL_PACKAGING_REQUIRED, INVOICE_REQUIRED, FORBIDDEN_CATEGORY, PRODUCT_SET_NOT_ALLOWED, MISSING_GPSR
"message": "Missing EORI number" // szczegółowe informacje dotyczące statusu
}
]
}
}
}
],
// ...
}
```

2. **Obsługa numerów seryjnych i numeru HS w zamówieniach**:

- dodaliśmy **nowy zasób** [POST /order/checkout-forms/{id}/serial-numbers](https://developer.allegro.pl/documentation#tag/Order-management/operation/setOrderLineItemsSerialNumbersUsingPOST) do przekazywania numerów seryjnych dla pozycji zamówienia (line items):
- liczba numerów seryjnych nie może być większa niż liczba sztuk danej pozycji zamówienia - orders[].lineItems[].quantity, 
- możliwa jest edycja i usuwanie numerów seryjnych przez podanie aktualnej listy. 

**Przykładowy request:**

```
{
"lineItems": [ // przedmioty wchodzące w skład zamówienia
"id": "8cf2a9a0-2136-11f1-806c-cfe0938beb3b",
"serialNumbers": { // nymery seryjne unikalne dla każdej sztuki towaru
"entries": [ // lista numerów seryjnych
{ "value": "SN1254353" },
{ "value": "SN4324211" }
]
}
]
}

```

- Dla zasobów do pobierania zamówień [GET /order/checkout-forms](https://developer.allegro.pl/documentation/#operation/getListOfOrdersUsingGET) oraz [GET /order/checkout-forms/{id}](https://developer.allegro.pl/documentation/#operation/getOrdersDetailsUsingGET): 
- rozszerzyliśmy zasoby o pole **"serialNumbers"** w sekcji **"lineItems"**, gdzie zwrócimy dodane numery seryjne - dostępne tylko w przypadku eksportu na Ukrainę,
- dla zamówień wysyłanych do Ukrainy w szczegółach zamówienia wyświetlimy kod taryfy celnej - numer HS produktu **"hsNumber"**, pobierany z parametrów oferty. 

**Przykładowy response (fragmenty)**:

```
{
"id": "8cf2a9a0-2136-11f1-806c-cfe0938beb3b",
"status": "READY_FOR_PROCESSING",
"invoice": {
"required": true,
"address": {
"street": "vul. Sumska 190, kv. 59",
"city": "Kharkiv",
"zipCode": "61001",
"countryCode": "UA",
"company": null,
"naturalPerson" {
"firstName": "Iwan",
"lastName": "Szewczenko"
}
},
"dueDate": null,
"features": null
},
"lineItems": [
{
"id": "8cf2a9a0-2136-11f1-806c-cfe0938beb3b",
"offer": {
"id": "10000000030",
"name": "Słuchawki bezprzewodowe",
...
"hsNumber": "8517130000" // kod taryfy celnej, unikatowy numer dla każdego produktu, pobierany z parametrów oferty, tylko dla zamówień z krajem dostawy UA ([Harmonized System (HS) Codes](https://www.trade.gov/harmonized-system-hs-codes))
},
"serialNumbers": { // numer seryjny unikalny dla każdej sztuki towaru
"expected": true, // wskazuje, czy trzeba dodać numery seryjne. Sprzedawca ma obowiązek podać numery seryjne podczas realizacji zamówienia, jeśli kraj docelowy tego wymaga, a kategoria produktu kwalifikuje się do podania numerów seryjnych.
"entries": [ // lista numerów seryjnych dodanych do zamówienia
{"value": "SN1254353"},
{"value": "SN4324211"}
]
}
}
],
...
"updatedAt": "2026-03-16T12:49:50.683Z",
"revision": "b3a81206"
}
```

----

From **May 25, 2026**, we will introduce new delivery methods supported by Allegro One in Poland dedicated to export to Ukraine, which involves customs clearance. To facilitate the shipment of such orders outside the European Union and process them, we will support sellers invited to the program with formal matters. The introduced changes are intended to obtain data that will allow our customs agency, One Customs, to represent sellers before customs and tax authorities. Therefore, among other things:
- we will block the ability to generate a transport label until the seller adds an invoice to the order,
- we will verify the compliance of the invoice with the data in order to avoid complications during customs clearance.

These changes will also cover the API - we will introduce new fields and resources to help verify and identify invoices and allow serial numbers to be provided for shipments exported to Ukraine.

### Who can use the export option?

The seller must meet the following conditions:

- meet the participation criteria and receive an **invitation** to the program,

- ship from a location **within the Allegro One courier's range**,

- have a **verified business account** with sales activation,

- provide an **EORI number** [in account settings](https://salescenter.allegro.com/account/data) (obtaining an EORI number: ),

- grant a p**ower of attorney to One Customs** to represent the seller's company before customs and tax authorities.

### When will an offer qualify for export to Ukraine?

- The delivery price list must include the **Allegro International Ukraina method**:

- Allegro International Courier Ukraine -  1f111ce-18a4-4a90-bf00-f999d9b97ac7
- Allegro International Pick-up Point Ukraine - 085a666f-7114-4063-9371-f999d9b97ac7
- Allegro International Parcel Lockers Ukraine - 0cb89f04-2203-45c7-b621-f999d9b97ac7

- It has completed **parameters**:

- **customs tariff code (HS number)** for each product, id: 250792 - minimum 8-digit CN (Combined Nomenclature) code or 10 and 12-character codes including the TARIC extension,
- **product weight with individual packaging**, id: 17448,

- **Buy Now** format,

- The offer **is not a product set**.

### What have we changed?

1. Invoice verification and identification:

- In the resource for creating an invoice object [POST /order/checkout-forms/{id}/invoices](https://developer.allegro.pl/documentation/#operation/addOrderInvoicesMetadata), the **"invoiceNumber"** field becomes **mandatory** when adding an invoice for export to Ukraine using the Allegro One delivery method.

- For the resource for retrieving invoice details [GET /order/checkout-forms/{id}/invoices](https://developer.allegro.pl/documentation#operation/getOrderInvoicesDetails):

- We added the **"orderMode"** field, which indicates the order mode: **REGULAR** or **UKRAINE_EXPORT**.
- We introduced a new **"verification"** structure that enables invoice verification in the context of export and contains the verification status and details.

**Example response with the new response structure (fragments)**:

```
{
"orderMode": "REGULAR", // possible values: REGULAR, UKRAINE_EXPORT
"invoices": [
{
// ...
"file": {
// ...
"verification": {
"status": "ACCEPTED_WITH_WARNINGS", // possible values - ACCEPTED, ACCEPTED_WITH_WARNINGS, REJECTED (potentially in the future), WAITING
"details": [ // details {
"type": "WARNING", // type of information (WARNING or ERROR)
"code": "MISSING_EORI_NUMBER", // available values NOT_VERIFIED_EORI, HSN_REQUIRED, INVALID_HSN, FORBIDDEN_HSN, WEIGHT_WITH_INDIVIDUAL_PACKAGING_REQUIRED, INVOICE_REQUIRED, FORBIDDEN_CATEGORY, PRODUCT_SET_NOT_ALLOWED, MISSING_GPSR
"message": "Missing EORI number" // detailed information regarding the status
}
]
}
}
}
],
// ...
}
```

2. **Handling serial numbers and HS number in orders**:

- We added a **new resource** [POST /order/checkout-forms/{id}/serial-numbers](https://developer.allegro.pl/documentation#tag/Order-management/operation/setOrderLineItemsSerialNumbersUsingPOST) for providing serial numbers for order items (line items):

- The number of serial numbers cannot be greater than the quantity of the given order item - orders[].lineItems[].quantity,
- It is possible to edit and delete serial numbers by providing the current list.

**Example request**:
```
{
"lineItems": [ // items included in the order
"id": "8cf2a9a0-2136-11f1-806c-cfe0938beb3b",
"serialNumbers": { // unique serial numbers for each unit of goods
"entries": [ // lista numerów seryjnych
{ "value": "SN1254353" },
{ "value": "SN4324211" }
]
}
]
}
```

- For resources to retrieve orders, [GET /order/checkout-forms](https://developer.allegro.pl/documentation/#operation/getListOfOrdersUsingGET) and [GET /order/checkout-forms/{id}](https://developer.allegro.pl/documentation/#operation/getOrdersDetailsUsingGET):

- We expanded the resources with the **"serialNumbers"** field in the **"lineItems"** section, where we will return the added serial numbers - available only for export to Ukraine.
- For orders shipped to Ukraine, the customs tariff code - product HS number **"hsNumber"**, retrieved from the offer parameters, will be displayed in the order details.

**Example response (fragments)**:
```
{
"id": "8cf2a9a0-2136-11f1-806c-cfe0938beb3b",
"status": "READY_FOR_PROCESSING",
"invoice": {
"required": true,
"address": {
"street": "vul. Sumska 190, kv. 59",
"city": "Kharkiv",
"zipCode": "61001",
"countryCode": "UA",
"company": null,
"naturalPerson" {
"firstName": "Iwan",
"lastName": "Szewczenko"
}
},
"dueDate": null,
"features": null
},
"lineItems": [
{
"id": "8cf2a9a0-2136-11f1-806c-cfe0938beb3b",
"offer": {
"id": "10000000030",
"name": "Słuchawki bezprzewodowe",
...
"hsNumber": "8517130000" // customs tariff code, a unique number for each product, retrieved from offer parameters, only for orders with delivery country UA ([Harmonized System (HS) Codes](https://www.trade.gov/harmonized-system-hs-codes))
},
"serialNumbers": { // unique serial number for each unit of goods
"expected": true, // indicates whether serial numbers need to be added. The seller is obliged to provide serial numbers during order fulfillment if the destination country requires it and the product category qualifies for serial numbers.
"entries": [ // list of serial numbers added to the order
{"value": "SN1254353"},
{"value": "SN4324211"}
]
}
}
],
...
"updatedAt": "2026-03-16T12:49:50.683Z",
"revision": "b3a81206"
}
```