Wysyłam z Allegro is a tool that facilitates parcel management on Allegro. Sellers can prepare parcels, print labels, and request a pickup of parcels by carriers from the specified address.

Learn more about API resources in the new guide.

Before you start using API Wysyłam z Allegro, activate your account via:

How to retrieve a list of delivery services

Use GET /parcel-management/delivery-services, to retrieve a list of delivery services available for an authorized user. In the response, you will receive delivery services defined for a user account:

  • delivery service ID,

  • delivery service name,

  • additional services within given delivery service,

Provide the carrier with a delivery service ID when creating a new parcel.


Sample request:

  
  curl -X GET \
  'https://api.allegro.pl/parcel-management/delivery-services’ \
  -H 'Authorization: Bearer {token}'  \
  -H 'Accept: application/vnd.allegro.public.v1+json' 
  


Sample response:

  
  {
    "services": [
        {
            "id": 8490564,							-- delivery service ID
            "name": " Allegro DPD"					-- delivery service name
	 		"additionalServices": {					-- additional services within given delivery 
													service
             	"cashOnDelivery": {			
          			"available": true,
         	 		"expressAvailable": true
        		},
        		"options": [						-- available delivery options
          			{
            		"name": "guarantee0930",		-- delivery option name
            		"description": "Delivery up to  -- delivery option description
                    9:30 / 10:30 (depending on location)"
          			}
        		]
      		},
      		"owner": "ALLEGRO"						-- contract owner with carrier, available
													values are ALLEGRO or CLIENT
        }
    ]}
 
  

How to create a new parcel

Remember that the delivery method selected by the buyer affects the delivery service you can choose. The delivery service applies to contracts signed by you or Allegro with a courier company.

The table below presents possible choices. You can check contract type in the owner field in the response to GET /parcel-management/delivery-services.

The delivery method chosen by the buyer Available own contract (delivery service) Available Allegro contract (delivery service)
Allegro DPD Courier any Allegro DPD
Allegro DPD courier, payment on delivery any Allegro DPD
Allegro UPS courier any Allegro UPS
Allegro Pocztex 48 courier any Allegro Poczta
Allegro Pocztex 48 courier, payment on delivery any Allegro Poczta
Allegro Punkty Poczta, Żabka, Orlen, Ruch any Allegro Poczta
Allegro registered mail any Allegro Poczta
Allegro Paczkomaty 247 InPost any Allegro Inpost*
Other any -


*Allegro Inpost contract requires that you add your own contract in the Wysyłam z Allegro settings and select “Używaj oferty dla sprzedawców Allegro” (Use the offer for Allegro Sellers).


Use PUT /parcel-management/parcel-create-commands/{commandId} to create a new parcel. As a commandId use a UUID number - generate it automatically on your own. Remember to use a new UUID number for each new parcel you create.


Click to view sample request:
curl -X PUT \
'https://api.allegro.pl/parcel-management/parcel-create-commands/14d3b9c4-ca3b-4e37-89c0-6f6cac24a02e’ \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Content-Type: application/vnd.allegro.public.v1+json' 
  -d 
‘{
  "serviceId": 8490564,                 -- required, delivery service ID, you can retrieve
                                        it via GET /parcels/delivery-services 
  "receiver": {                         -- receiver data
    "address": {
      "street": "Testowa 172",                  
      "postCode": "61-132",         
      "city": "Poznań",             
      "countryCode": "PL"               -- country code in ISO 3166-1 alpha-2 format
    },
    "email": "hamu7udk3p+17454c1b6@allegromail.pl",  -- required, email address. Must be a 
                                                    valid buyer email generated by Allegro.
    "name": "Jan Kowalski",         
    "company": "Allegro.pl sp. z o.o.",     
    "phone": "500600700",           
    "pointId": "1234567"                -- required, if parcel is shipped from a pickup point.
                                        You can retrieve pickup point ID from the order via
                                        GET /order/checkout-forms
  },
  "pickup": {                           -- required, sender data
    "address": {                    
      "street": "Testowa 8",            
      "postCode": "10-200",         
      "city": "Warszawa",           
      "countryCode": "PL"               -- country code in ISO 3166-1 alpha-2 format
    },
    "email": "email@mail.com",      
    "name": "Jan Kowalski",         
    "company": "Allegro.pl sp. z o.o.",     
    "phone": "500600700",           
    "pointId": "1234567"                -- required, if parcel is shipped from a pickup point.
                                        You can retrieve pickup point ID from order via
                                        GET /order/checkout-forms
  },
  "items": [                            -- required, parcel items details
    {
      "weight": {               
                  "value": 20,
                  "unit": "KILOGRAM"
          },    
      "dimensions": {                       
        "height": {             
                  "value": 20,
                  "unit": "CENTIMETER"
          },                
        "width": {              
                  "value": 20,
                  "unit": "CENTIMETER"
          },                
        "depth": {              
                  "value": 20,
                  "unit": "CENTIMETER"
          },                
      },
      "description": "Car wheels.",             
      "value": {                        -- declared parcel value
        "amount": "2.50",
        "currency": "PLN"
      }
    }
  ],
  "type": "PACKAGE",                    -- required, parcel type
  "label": {                            -- not required, information on the label
    "sender": {                 
      "address": {
        "street": "Testowa 8",
        "postCode": "10-200",
        "city": "Warszawa",
        "countryCode": "PL",
        "county": null,                 -- not required, provide value only if shipment 
                                        is from Ireland, USA or Canada
      },
      "email": "email@mail.com",
      "name": "Jan Kowalski",
      "company": "Allegro.pl sp. z o.o.",
      "phone": "500600700"
    },
    "fileFormat": "PDF",                -- label file format
    "referenceNumber": "abcd1234"       -- parcel identifier in your own system
  },
   "additionalServices": {              -- additional services. Only the options that you 
                                        received in response to GET 
                                        /parcel-management/delivery-services are available
     "cashOnDelivery": {
       "value": {
         "amount": "2.50",
         "currency": "PLN"
       },
       "accountNumber": "12345678901234567890123456",
       "name": "Jan Kowalski",
        "express": false
      },
    "options": [
      "guarantee0930"
    ]
  }
}’


Note! You will receive a 201 Created status in the response, but remember that this does not mean that the parcel has been created correctly. In the response header Retry-After, we will return information on how many seconds you need to wait until you can check task status via GET parcel-management/parcel-create-commands/{commandId}.

How to check parcel creation status

You can check parcel creation status via GET /parcel-management/parcel-create-commands/{commandId}. If a task is not finished, we will return a Retry-After header which you can check for information on how many seconds you need to wait until you can check command status.


Sample request:

  
  curl -X GET \ 
  'https://api.allegro.pl/parcel-management/parcel-create-commands/14d3b9c4-ca3b-4e37-89c0-6f6cac24a02e’ \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json'
  


Sample response:

  
  {
    "id": "14d3b9c4-ca3b-4e37-89c0-6f6cac24a02e",   -- UUID number from your request
    "parcelId": "7739951",				   
    "status": "SUCCESS",				  			-- task status, available values are:
							  						IN_PROGRESS, SUCCESS, ERROR
    "errors": []						
  }

Sample response when you do not provide the building number:

  
  {
    "id": "279b7e5a-640a-4c6b-82ae-99446a64bf52",
    "parcelId": null,
    "status": "ERROR",
    "errors": [
        {
            "code": "VALIDATION_ERROR",
            "message": "Brak numeru budynku",
            "details": null,
            "path": "receiver.street",
            "userMessage": null
        }
    ]
  }
  


Sample response when you provide an invalid phone number:

  
  {
    "id": "610ea12b-6a5b-4ebe-9ed4-a387b6dcab7e",
    "parcelId": null,
    "status": "ERROR",
    "errors": [
        {
            "code": "VALIDATION_ERROR",
            "message": "Niepoprawny numer telefonu (może zawierać od 9 do 14 cyfr)",
            "details": null,
            "path": "receiver.phone",
            "userMessage": null
        }
    ]
  }
  

How to retrieve parcel details

Use GET /parcel-management/parcels/{parcelId} to get parcel details. Provide parcelID retrieved via GET /parcel-management/parcel-create-commands/{commandId}.


Sample request:

  
  curl -X GET \
  'https://api.allegro.pl/parcel-management/parcels/7740851’ \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json' 
 

Click to view sample response:
curl -X PUT \
'https://api.allegro.pl/parcel-management/parcel-create-commands/14d3b9c4-ca3b-4e37-89c0-6f6cac24a02e’ \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Content-Type: application/vnd.allegro.public.v1+json' \
  -d 
 ‘{
    "parcelId": "7740851",                      
    "serviceId": 8490564,                       
    "label": {
        "sender": {
            "name": "Jan Kowalski",
            "company": "Allegro.pl sp. z o.o.",
            "address": {
                "street": "Testowa 10",
                "postCode": "61-132",
                "city": "POZNAŃ",
                "county": null,
                "countryCode": "PL"
            },
            "email": "email@mail.com",
            "phone": "500600700"
        },
     "fileFormat": "PDF",                       
     "referenceNumber": "abcd1234",             
    },
    "receiver": {                               
        "name": "Jan Kowalski",
        "company": "Allegro.pl sp. z o.o.",
        "address": {
            "street": "Testowa 7",
            "zipCode": "61-132",
            "city": "POZNAŃ",
            "county": null,
            "countryCode": "PL"
        },
        "pointId": null,
        "email": "sdasd@allegromail.pl",
        "phone": "500600700"
    },
    "pickup": {                                 
        "name": "Jan Kowalski",
        "company": "Allegro.pl sp. z o.o.",
        "address": {
            "street": "Testowa 8",
            "zipCode": "61-132",
            "city": "POZNAŃ",
            "county": null,
            "countryCode": "PL"
        },
        "pointId": null,
        "email": "email@mail.com",
        "phone": "500600700"
    },
    "items": [                                  
        {
            "waybill": "0000000767923Q",        
            "weight": {                         
                "value": 20,
                "unit": "KILOGRAM"
        },      ,           
            "dimensions": {                     
                "height": {                     
                  "value": 20,
                  "unit": "CENTIMETER"
          },        
                "width": {                      
                  "value": 20,
                  "unit": "CENTIMETER"
          },    
                "depth": {                      
                  "value": 20,
                  "unit": "CENTIMETER"
          },    
            },
            "description": "Wheels.",       
            "value": {                          
                "amount": "2.5",
                "currency": "PLN"
            }
        }
    ],
    "type": "PACKAGE",                          
    "additionalServices": {},                   
    "state": null                              -- current parcel status. Available values are: 
                                               DRAFT (will occur when you create a parcel by
                                               GUI as a draft, then via API you get its details),
                                               CREATED and CANCELLED 
                
  }’

How to cancel a parcel

You can cancel a parcel via PUT /parcel-management/cancel-commands/{commandId}. In your request structure provide a parcelId.


Sample request:

  
  curl -X PUT \
  'https://api.allegro.pl/parcel-management/parcel-cancel-commands/14d3b9c4-ca3b-4e37-89c0-6f6cac24a02e’ \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Content-Type: application/vnd.allegro.public.v1+json' 
  -d ‘{
	"parcelId": "7740818"			
   }’
   


Note! You will receive 201 Created status in the response, but remember that this does not mean that the parcel has been canceled correctly. In the response header Retry-After, we will return information on how many seconds you need to wait until you can check task status via GET /parcel-management/parcel-cancel-commands/{commandId}. The SUCCESS status does not guarantee that the shipment of the parcel has been canceled, e.g. you can not cancel the parcel which courier picked up or posted in a parcel locker (paczkomat).

How to check parcel cancellation status

You can check parcel cancellation status via GET /parcel-management/parcel-cancel-commands/{commandId}. If a task is not finished, we will return a Retry-After header in which you can check information on how many seconds you need to wait until you can check command status.


Sample request:

  
  curl -X GET  \
  'https://api.allegro.pl/parcel-management/parcel-cancel-commands/7832d3ff-9dd8-4473-9f4a-ebdeb0b73261’ \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json' 
 

Sample response:

  
  {
    "id": "7832d3ff-9dd8-4473-9f4a-ebdeb0b73261",        -- UUID number from your request
    "status": "SUCCESS",				     			 -- task status, available values are:
							                             IN_PROGRESS, SUCCESS (does not 
                                                         guarantee that the shipment of the 
                                                         parcel has been canceled, e.g. you can 
                                                         not cancel the parcel which was picked  
                                                         up by a courier or posted in a parcel 
                                                         locker (paczkomat).
    "errors": []						      			
  }
 
 

How to check pickup date proposals

Use GET /parcel-management/pickup-date-proposals to retrieve pickup date proposals. Pickup takes place when the courier arrives to take parcels for shipment. In your request provide parameters:

  • parcelId - required, can be retrieved in the response to GET parcel-management/create-commands/{commandId}. You can pass maximally 100 parcels, e.g. parcelId=7740851&parcelId=7740818. For each parcel we will return separate date range;
  • readyDate - not required, date when parcels will be ready for pickup. not required, date when parcels will be ready for pickup. Provide the date in the following format - YYYY-MM-DD, e.g. 2020-07-10.

In the response, in the proposals array, you will receive a set of packages with the proposed pickup date and hour range. You will provide the chosen date in the next step when you request a pickup by a courier.

Note! Pocztex Courier doesn’t supports pickup for parcels, the parcel can only be posted at the sending point. In this case, you will receive empty array in the response.


Sample request:

  
  curl -X GET \
  'https://api.allegro.pl/parcel-management/pickup-date-proposals?parcelId=7740851&parcelId=7740818&readyDate=2020-07-08’ \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json' 

 

Click to view sample response:
{
    "parcelsProposals": [           
        {
            "parcelId": "7740818",          
            "proposals": [                  
                        kuriera
                {
                    "date": "2020-07-08",   
                    "minTime": "10:00",     
                    "maxTime": "14:00"      
                },
                {
                    "date": "2020-07-08",
                    "minTime": "12:00",
                    "maxTime": "14:00"
                },
                {
                    "date": "2020-07-08",
                    "minTime": "14:00",
                    "maxTime": "16:00"
                },
                {
                    "date": "2020-07-08",
                    "minTime": "15:00",
                    "maxTime": "17:00"
                },
                {
                    "date": "2020-07-08",
                    "minTime": "16:00",
                    "maxTime": "18:00"
                }
            ]
        },
        {
            "parcelId": "7740851",
            "proposals": [
                {
                    "date": "2020-07-08",
                    "minTime": "10:00",
                    "maxTime": "14:00"
                },
                {
                    "date": "2020-07-08",
                    "minTime": "12:00",
                    "maxTime": "14:00"
                },
                {
                    "date": "2020-07-08",
                    "minTime": "14:00",
                    "maxTime": "16:00"
                },
                {
                    "date": "2020-07-08",
                    "minTime": "15:00",
                    "maxTime": "17:00"
                },
                {
                    "date": "2020-07-08",
                    "minTime": "16:00",
                    "maxTime": "18:00"
                }
            ]
        }
    ]
  }

How to request parcel pickup by a courier

Use PUT /parcel-management/parcel-pickup-request-commands/{commandId} to request pickup for parcels. As a commandId pass UUID - generate it automatically on your own. Use a UUID number as a commandId pass - generate it automatically on your own. Remember to use a new UUID number for each new parcel you create.

Sample request:

   
  ccurl -X PUT \
  'https://api.allegro.pl/parcel-management/parcel-pickup-request-commands/deb2238a-f7ac-4e12-89c9-537583143203’ \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Content-Type: application/vnd.allegro.public.v1+json' \
  -d ‘
  {
  "parcelIds": [				-- array of parcel IDs for pickup by a courier
    "7740851",
    "7740818"
  ],
  "pickupDate": {				-- information about pickup date and hour range for 
  								pickup. Provide the same values which you
								received in the response to 
								GET /parcel-management/pickup-date-proposals
    "date": "2020-05-01",		
    "minTime": "10:00",			
    "maxTime": "14:00"			
   }
  }’

 


Note! You will receive 201 Created status in the response, but remember that this does not mean that the pickup has been requested correctly. In the response header Retry-After, we will return information on how many seconds you need to wait until you can check command status - after that time check task status via GET /parcel-management/parcel-pickup-request-commands{commandId}.

How to check parcel pickup request status

Use GET /parcel-management/parcel-pickup-request-commands/{commandId} to check parcel pickup request status. If a task is not finished, we will return a Retry-After header in which you can check information on how many seconds you need to wait until you can check command status.


Sample request:

  
  curl -X GET \
  'https://api.allegro.pl/parcel-management/parcel-pickup-request-commands/deb2238a-f7ac-4e12-89c9-537583143203’ \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json' 
  


Sample response:

  
  {
    "id": "deb2238a-f7ac-4e12-89c9-537583143203",   -- UUID number from your request
    "status": "SUCCESS",				   			task status, available values are:
							      					IN_PROGRESS, SUCCESS,
 							      					PARTIAL_SUCCESS, ERROR
    "errors": []						  			
  }
 
  

How to create a label for parcel

Use GET /parcel-management/parcels/label to download labels for created parcels. In your request, provide parameters:

  • parcelId,
  • pageFromat - not required, page format. Provide the value “A4” or “A6”. Applies only for files in PDF format.

In the response, you will receive a PDF, EPL or ZPL file (depending on the format selected at the parcel creation stage) which needs to be saved on your disk. Remember to provide the Accept header correctly.


Sample request:

  
  curl -X GET \
  'https://api.allegro.pl/parcel-management/label?parcelId=7740851&pageFormat=A4’
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/pdf' \         // or plain/text
  -H ‘Content-Type: application/pdf'     // or plain/text
  


Sample response:

  
  Status 200 OK
  

How to retrieve parcel protocol

Use GET /parcel-management/parcels/protocol to retrieve parcel protocol. In your request, provide parcel IDs in parcelId parameters, e.g. parcelId=1233&parcelId=1234. In the response, you will receive a PDF file which needs to be saved on your disk. The document will be generated in two copies – one for the seller and one for the courier. Remember to provide the Accept header correctly.


Sample request:

  
  curl -X GET \
  'https://api.allegro.pl/parcel-management/protocol?parcelId=7740851&parcelId=7740818’ \
  -H 'Authorization: Bearer {token}' \ 
  -H 'Accept: application/pdf' \
  -H ‘Content-Type: application/pdf'
  


Sample response:

  
  Status 200 OK