How to listing ads

Advertisement

1/ Prepare a draft

At first, prepare a draft by calling POST /sale/offers. The draft does not have to be complete as you can finish it up later. Add more information at any time by calling PUT /sale/offers/{offerId}.

Use drafts to:

  • store ads data on our servers
  • prepare a preview.


2/ Assign the package and additional options

Assign the package and additional options to a complete draft.

Retrieve available packages and additional options by calling GET /sale/classifieds-packages?category.id={category-id} , then assign selected options by calling PUT /sale/offer-classifieds-packages/{offer-id}.


3/ List your ad

List the ads on Allegro.pl. For this purpose, transfer ACTIVATE when calling PUT /sale/offer-publication-commands/{commandId}. The status will be ACTIVATING until the offer is published on the site. The same status is applied to offers with scheduled listing date.


4/ Check the status

Once the ad is listed, its status will be changed to ACTIVE. The exact listing date is displayed in the field scheduledAt after calling GET /sale/offer-publication-commands/{commandId}/tasks. Use the same method to close the ad by transferring END.

Listing ads – step by step

1. Required data

Use supportive methods to retrieve ID of necessary elements:

Contact data

Resources for managing contacts:

Note!

  • You cannot have more than 50 contacts,
  • Within one contact you can provide up to::
    • 1 email address,
    • 2 phone numbers..

POST /sale/offer-contacts - use this resource to create a new contact. You must be logged in as a seller listing the ad.

Sample request:

 
  curl -X POST \
  'https://api.allegro.pl/sale/offer-contacts' \
  -H 'Content-Type: application/vnd.allegro.public.v1+json' \
  -H 'Accept: application/vnd.allegro.public.v1+json’ \
  -H 'Authorization: Bearer {token}' \
  -d '{
  "name": "Auta terenowe",      -- contact name; required; maximum number of characters – 250
  "emails": [                   -- email addresses; you can provide one
    {
      "address": "test@test.pl"
    }
  ],
  "phones": [                   -- phone numbers; you can provide up to two
    {
      "number": "555-555-666"
    },    
    {
      "number": "555555667"
    }
  ]
 }’
 

Sample response:

 
  ‘{
    "id": "0c046252-9559-4ecb-8ea3-879f60e46947",   -- contact identifier (contact.id)
    "name": "Auta terenowe",                        -- contact name
    "emails": [
        {
            "address": "test@test.pl"
        }
    ],
    "phones": [
        {
            "number": "+48 55 555 57 77"
        }
    ]
  }’
 


GET /sale/offer-contacts/{contact.id} - use this resource to retrieve contact details. Provide contact UUID in URL.

Sample request:

 
  curl -X GET \
  ‘https://api.allegro.pl/sale/offer-contacts/0c046252-9559-4ecb-8ea3-879f60e46947' \
  -H 'Accept: application/vnd.allegro.public.v1+json’ \
  -H 'Authorization: Bearer {token}’
 

Sample response:

 
  ‘{
    "id": "0c046252-9559-4ecb-8ea3-879f60e46947",       -- contact identifier (contact.id)
    "name": "Auta terenowe",                            -- contact name
    "emails": [
        {
            "address": "test@test.pl"
        }
    ],
    "phones": [
        {
            "number": "+48 55 555 57 77"
        }
    ]
  }’
 


GET /sale/offer-contacts - use this resource to retrieve details of all contacts assigned to a user account.

Sample request:

 
  curl -X GET \
  'https://api.allegro.pl/sale/offer-contacts' \
  -H 'Accept: application/vnd.allegro.public.v1+json’ \
  -H 'Authorization: Bearer {token}’
 

Sample response:

 
  ‘{
    "contacts": [
        {
            "id": "0c046252-9559-4ecb-8ea3-879f60e46947",   -- contact identifier (contact.id)
            "name": "Auta terenowe",                        -- contact name
            "emails": [
                {
                    "address": "test@test.pl"
                }
            ],
            "phones": [
                {
                    "number": "+48 788 788 788"
                },
                {
                    "number": "+48 75 575 57 55"
                }
            ]
        },
        {
            "id": "af1ccfd7-2753-4ed3-bdda-c78eb14442ab",
            "name": "Auta osobowe",
            "emails": [
                {
                    "address": "test@test.pl"
                }
            ],
            "phones": [
                {
                    "number": "+48 55 555 57 77"
                }
            ]
        },
        {
            "id": "27869b31-048e-43a0-bdc0-52b922f278a5",
            "name": "Ciężarówki",
            "emails": [
                {
                    "address": "test@test.pl"
                }
            ],
            "phones": []
        }
    ]
   }’
 


PUT /sale/offer-contacts/{contact.id} - use this resource to update contact data. Provide contact UUID in URL

Sample request:

 
  curl -X PUT
  'https://api.allegro.pl//sale/offer-contacts/12f43efd-2369-480d-9f945178eeb9c663' \
  -H 'Content-Type: application/vnd.allegro.public.v1+json' \
  -H 'Accept: application/vnd.allegro.public.v1+json’ \
  -H 'Authorization: Bearer {token}’ \
  -d '{
   "name": "Auta terenowe",
   "emails": [
     {
       "address": "test@test.pl"
     }
   ],
   "phones": [
     {
       "number": "555-555-777"
     }
   ]
 }’
 

Sample response:

 
  ‘{
    "id": "0c046252-9559-4ecb-8ea3-879f60e46947",
    "name": "Auta terenowe",
    "emails": [
        {
            "address": "test@test.pl"
        }
    ],
    "phones": [
        {
            "number": "+48 55 555 57 77"
        }
    ]
  }’
 

List of promo options

If you want to list an ad, you have to select a package and decide whether you also want to buy additional promo options. The following REST API resources will help you manage packages and additional options:

  • GET /sale/classifieds-packages?category.id={category-id} - retrieve packages and additional options available in the category,
  • GET /sale/classifieds-packages/{package-id} - retrieve package/additional option details.

At first, call GET /sale/classifieds-packages?category.id={category-id} to retrieve identifiers of packages and additional options available in the category.


Sample request:

 
  curl -X GET \
  ‘https://api.allegro.pl/sale/classifieds-packages?category.id={category-id}’ \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json'
 

Sample response:

 
  '{
    "packages": [{
            "id": "6174be19-56f9-484b-b72c-43b0b00785e8",    
            "type": "BASE"                                  
            "name": "Podstawowy",                           
            "publication": {
                "duration": "PT960H"                        -- ad duration
            },
            promotions: [{                                  -- types of featuring options
                                                            available in the package
                    "name": "bold"
                    "duration": "PT240H"
                },
                {
                    "name": "emphasized"
                    "duration": "PT120H"
                },
                ...
            ],
            "extensions": [{                                -- extensions available in
                                                            a particular package
                "name": "autocentrumExport",
                "description": "Eksport ogłoszenia do autocentrum"
            }]
        },
        {
            "id": "3174be19-56f9-484b-b72c-43b0b00785e8",
            "type": "EXTRA"                                 -- type of additional options you can
                                                            buy to expand the package
            "name": "Dodatkowe wyróżnienie na 10 dni",
                                                            -- name of available additional option
            promotions: [{                                  -- types of featuring options available
                                                            in a particular additional
                                                            option of the package
                    "name": "bold"
                    "duration": "PT240H"
                },
                {
                    "name": "emphasized"
                    "duration": "PT120H"
                },
                ...
            ]
        }
    ]
  }'
 

Call GET /sale/classifieds-packages/{package-id} to retrieve detailed information concerning the package and available additional options.

Sample request:

 
  curl -X GET \
  ‘https://api.allegro.pl/sale/classifieds-packages/6174be19-56f9-484b-b72c-43b0b00785e8’ \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json'
        
 '{
    "id": "6174be19-56f9-484b-b72c-43b0b00785e8",   
    "type": "BASE"                                  
    "name": "Podstawowy",                           
    "publication": {
        "duration": "PT960H"                        -- duration of the classified ad
    },
    promotions: [{                                  -- types of featuring options
                                                    available in the package
            "name": "bold"
            "duration": "PT240H"
        },
        {
            "name": "emphasized"
            "duration": "PT120H"
        },
        ...
    ],
    "extensions": [{                                -- extensions available in
                                                    the package
            "name": "autocentrumExport",
            "description": "Eksport ogłoszenia do autocentrum"
        }
    }]'
	
 

2. Category number and parameters

Use the below resources to retrieve IDs of particular categories and parameters you need to provide

Category ID

Call GET /sale/categories?parent.id={categoryId} to retrieve a list of categories that belong to provided superior category (or a list of main categories). Remember – ads can be listed in the lowest tier category if the category is marked “leaf”: true.

NOTE! If you call GET /sale/categories without providing any category, you will retrieve IDs of main Allegro categories. Use the identifiers to get in the next call to the lowest tier categories (remember – ads can be listed in the lowest tier category if the category is marked “leaf”: true).

Sample request:

 
  curl -X GET \
  'https://api.allegro.pl/sale/categories?parent.id=4032’ \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Authorization: Bearer {token}' 
 

Sample response:

 
 '{
    "categories": [
        {
            "id": "249626",
            "name": "Seria 2",
            "parent": {
                "id": "4032"
            },
            "leaf": true,                               -- information whether the category is
                                                        of the lowest tier that supports ads
            "options": {
                "variantsByColorPatternAllowed": true,  -- information whether the parameter  
                                                        can be used in the multi-variant feature.
                                                        two values are supported:
                                                        true (yes) and false (no).
                "advertisement": true,                  -- information whether the category
                                                        supports ads
                "advertisementPriceOptional": false     -- information whether the category
                                                        supports ads without provided price
            }
        },
        {
    …
        },
        {
            "id": "146805",
            "name": "Seria 4",
            "parent": {
                "id": "4032"
            },
            "leaf": true,
            "options": {
                "variantsByColorPatternAllowed": true,
                "advertisement": true,
                "advertisementPriceOptional": false
            }
        }
    ]
  }'
 

Parameters

Call GET /sale/categories/{categoryId}/parameters to retrieve a list of parameters supported by the category you indicated. Every time a list of parameters supported by the called category is returned.

Note! Retrieve parameters, verify and update them, in particular these of dictionary type because their values may change.

Sample request:

 
  curl -X GET \
  'https://api.allegro.pl/sale/categories/57968/parameters’ \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Authorization: Bearer {token}'
 

Click to view sample response:
  ‘{
    "parameters": [                         -- list of parameters supported
                                            by the particular category
        {
            "id": "11323",                  -- parameter ID
            "name": "Stan",                 -- parameter name
            "type": "dictionary",           --  parameter type; supported values:
                                            dictionary (dictionary; one-time,
                                            or multiple choice, depending on the value in
                                            multipleChoices), integer,
                                            float (floating-point numbers), string (you can add
                                            one or more values)
            "required": true,               -- information whether a particular parameter is required
            "unit": null,
            "options": {
                "variantsAllowed": true,    -- information whether the parameter  
                                            can be used in the multi-variant feature.
                "variantsEqual": false      -- information whether the parameter is of verification
                                            type If the returned value is true, then all variants
                                            must have the same value in this parameter
            },
            "dictionary": [
                {
                    "id": "11323_1",        -- parameter value you should transfer in
                                            the ad model
                    "value": "Nowy"
                },
                {
                    "id": "11323_2",
                    "value": "Używany"
                },
                {
                    "id": "11323_238062",
                    "value": "Uszkodzony"
                }
            ],
            "restrictions": {
                "multipleChoices": false    -- this parameter enables choosing one or
                                            more values
            }
        },
        {
            "id": "1",
            "name": "Rok produkcji",
            "type": "integer",
            "required": true,
            "unit": null,
            "options": {
                "variantsAllowed": true,
                "variantsEqual": false
            },
            "restrictions": {
                "min": 1900,
                "max": 2100,
                "range": false              -- prange parameter. Min and max range sections
                                            define the minimum and maximum
                                            value of a parameter.
            }
        },
       …
        {
            "id": "215898",
            "name": "Numer VIN",
            "type": "string",
            "required": false,
            "unit": null,
            "options": {
                "variantsAllowed": false,
                "variantsEqual": false
            },
            "restrictions": {
                "minLength": 12,
                "maxLength": 17,
                "allowedNumberOfValues": 1  -- information on number of values
                                            you can provide in this parameter
            }
        }
    ]
}’

Note! In the case of PUT and POST methods provide identifiers, not parameter values. Sample structure of parameters depending on the ad type:

  • for dictionary parameters (selecting one or many values)

      
      {
        "id": "209878",
        "valuesIds": [
        "209878_2",
        "209878_1"
        ],
        "values": [],
        "rangeValue": null
      }
     

  • for range parameters

      
      {
        "id": "212570",
        "valuesIds": [],
        "values": [],
        "rangeValue": {
            "from": "80",
            "to": "100"
         }
      }
     

  • for parameters you fill in

      
      {
        "id": "216325",
        "valuesIds": [],
        "values": [
            "zielony",
            "żółty",
            "czerwony"
        ],
        "rangeValue": null
      }
     

3. Photos

Call POST /sale/images to upload photos via HTTP and HTTPS protocols (with valid certificate) to our servers. You will receive an address of uploaded image you can use in the gallery. Note! Rules concerning photos in a gallery and description are provided here. There are two upload methods:

  • as a link

	
	curl -X POST \
    https://upload.allegro.pl/sale/images \
    -H 'Authorization: Bearer {token}' \
    -H 'Accept: application/vnd.allegro.public.v1+json' \
    -H 'Content-Type: application/vnd.allegro.public.v1+json' \
    -d '{
         "url":"https://imgur.com/1aOIvg3E.jpg"       -- wymagane, link do obrazka
        }'
		

- binary format
    curl -X POST \
    'https://upload.allegro.pl/sale/images
    -H 'Authorization: Bearer {token}' \
    -H 'Accept: application/vnd.allegro.public.v1+json' \
    -H 'Content-Type: "image/jpeg", "image/png"' \
    -H 'Accept-Language: pl-PL', (albo en-EN) \
    --data-binary "@file_to_upload.png"				-- wymagane, zawartość pliku z
													obrazkiem w postaci binarnej

Sample response:

  • 401 - unauthorized

  • 413 - image is too big

  • 415 - incorrect image type

  • 201 - image uploaded correctly, response body:

	{
    "expiresAt":"2018-04-06T16:38:04.930Z",         -- file expiration date
                                                    (removal from server).
                                                    We will not remove it if
                                                    you use the photo in the ad.
    "location":"https://1.allegroimg.com/original/110843/cd7d40b84968ab8d79ab8a2e47a1"
                                                    -- link to uploaded photo
	}

4. Title of the ad

The title cannot exceed 50 characters. The list of supported letters, numbers and special signs is provided below.

	Letters 'a','b','c','d','e','f','g','h','i','j','k','l','m','n','o','p','q','r','s','t','u','w','v','x','y','z',
    'ä','ö','ü','ø','ò','ß','0','á','č','ě','í','ř','š','ů','ú','ý','ž','œ','æ','à','â','ç','é','è','ê','ë','î',
    'ï','ô','û','ù','ü','ÿ','€','×','ą','ć','ę','ł','ń','ó','ś','ź','ż','µ','⌀',

    Numbers '0','1','2','3','4','5','6','7','8','9',

    Special signs:'!','@','[',']','#','$','%','^','&','*','{','}','(',')','.',',','/','\\','|','?',' ',';','~','²','³',
    '`','\'','’','´','\"','”','"','„','“','″','<','>','_','\t',':','-','=','+','0','…','–','°','°'
Note! Some letters and special signs are changed to entities and for this reason they may take more than one character. For example, & is changed to &amp; and for this reason, it is treated as 5 characters.

5. Description

For more information on new rules concerning classified ads and offers please refer to seller’s page.

Important information:

  • the maximum description size you can transfer is 40000 bytes

  • use only the following HTML tags:

    • h1 - title

    • h2 - subtitle

    • p - paragraph

    • ul - unordered (bulleted) list

    • ol - ordered list

    • li - list item

    • b - bold.

  • use only images that are saved in the ad gallery that are transferred in the images array.

We recommend drafting the first description using a listing form. Use all types of sections and text formatting options, and retrieve the ad by using GET /sale/offers/{offerId}. This is the easiest way to learn how to prepare a correct description.

Structure of a new description

Sections

The offer description consists of at least one section located in the sections array. The description can have up to 100 sections.

	{
    	"sections": [
        	{ section1 },
        	{ section2 },
         	...
        	]
	}

Description elements (item)

Sections group description elements (item) in a column view:

  • one screen width column

    	{
         	"items" : [
         	{ item1 }
         	]
    	}

  • two columns (50% of screen width)

    	{
         	"items" : [
         	{ item1 }
         	{ item2 }
         	]
    	}

  • You cannot create a section with more columns. structure

Types of content in the description

Text

	{
      "type": "TEXT",
      "content": "<p>opis tekstowy</p>"
	}

You can use the following HTML tags:

  • h1 - title

  • h2 - subtitle

  • p - paragraph

  • ul - unordered (bulleted) list

  • ol - ordered list

  • li - list item

  • b - bold

Key rules:

  1. You must put content in HTML tags. Use only lower case letters in HTML tag.
    Correct

    	{
          "type": "TEXT",
          "content": "<p>opis tekstowy</p>"
    	}
     
    Incorrect
    	{
          "type": "TEXT",
          "content": "opis tekstowy"
    	}
     

  2. You cannot format h1 and h2 tags.
    Correct

    	{
           "type": "TEXT",
           "content": "<h1>Tytuł sekcji</h1>"
        }
     
    Incorrect
    	{
          "type": "TEXT",
          "content": "<h1><b>Tytuł sekcji<b></h1>"
    	}
     

  3. You can use < b > < /b > tags in::

    • < p > < /p > - paragraph
    • < ul > < /ul > - unordered (bulleted) list
    • < ol > < /ol > - ordered list
  4. You can use < p > < /p > tags in:

    • < ul > < /ul > - unordered (bulleted) list
    • < ol > < /ol > - ordered list

How to combine HTML tags:

	<h1>Lorem ipsum dolor sit amet, consectetur adipiscing elit</h1>
    <p><b>Aliquam vitae nisi ac lectus gravida rhoncus</b>. Vivamus egestas, orci quis
    fermentum sollicitudin, leo urna pellentesque quam, ut mattis risus nisl sed dolor.</p>
    <ul>
        <li><b>Nulla eu justo ut velit pellentesque porta.</b></li>
        <li>Pellentesque eget arcu id ligula consequat fermentum at nec velit. Maecenas vitae nunc
        non ante aliquet facilisis nec id leo.</li>
        <li>Sed vitae metus vel lorem iaculis rhoncus.</li> <li>Nullam nec felis felis.</li>
    </ul>
    <ol>
        <li><p><b>In eget vulputate purus</b></p></li>
        <li><p>Integer a pharetra odio.</p></li>
        <li><p>Vestibulum ut vestibulum diam.</p></li>
        <li><p>Phasellus quis tempor ipsum, at tincidunt nibh.</p></li>
        <li><p>Nulla sollicitudin, libero sit amet fermentum iaculis.</p></li>
    </ol>

Images

You can use only images you have previously transferred by calling POST on /sale/images.

	{
    	"type": "IMAGE",
    	"url": "https://d.allegroimg.com/original/0313bd/338d11a74b059fea784beee0084d"
	}

Sample structure of an offer description:

{
	[
		{
    		"sections": [{
        	"items": [{
            	"type": "TEXT",
            	"content": "<p>tekstowy opis przedmiotu</p>"
        	}]
    	}, {
        	"items": [{
            	"type": "IMAGE",
            	"url": "https://d.allegroimg.com/original/0313bd/338d11a74b059fea784beee0084d"
        	}]
    	}, {
        	"items": [{
            	"type": "TEXT",
            	"content": "<p>tekstowy opis przedmiotu</p>"
        	}, {
            	"type": "IMAGE",
            	"url": "https://f.allegroimg.com/original/037738/bc72c2f24784b50774d7d078c7ef"
        	}]
    	}, {
        	"items": [{
            	"type": "IMAGE",
            	"url": "https://0.allegroimg.com/original/032ac4/9c10035846bb970cf208f6982fc0"
        	}, {
            	"type": "IMAGE",
            	"url": "https://d.allegroimg.com/original/0313bd/338d11a74b059fea784beee0084d"
        	}]
    	}]
	}

Sample description structure

{
	[
		{
    		"sections": [{
        	"items": [{
            	"type": "TEXT",
            	"content": "<p>tekstowy opis przedmiotu</p>"
        	}]
    	}, {
        	"items": [{
            	"type": "IMAGE",
            	"url": "https://d.allegroimg.com/original/0313bd/338d11a74b059fea784beee0084d"
        	}]
    	}, {
        	"items": [{
            	"type": "TEXT",
            	"content": "<p>tekstowy opis przedmiotu</p>"
        	}, {
            	"type": "IMAGE",
            	"url": "https://f.allegroimg.com/original/037738/bc72c2f24784b50774d7d078c7ef"
        	}]
    	}, {
        	"items": [{
            	"type": "IMAGE",
            	"url": "https://0.allegroimg.com/original/032ac4/9c10035846bb970cf208f6982fc0"
        	}, {
            	"type": "IMAGE",
            	"url": "https://d.allegroimg.com/original/0313bd/338d11a74b059fea784beee0084d"
        	}]
    	}]
	}

6. Draft ad

To do so, call POST /sale/offers. You must be logged in as an authenticated and authorized user. Once the draft ad is created, you can publish it later on the site. You can transfer partial data (at least title and ad category) and then complete the draft by calling PUT /sale/offers/{offerId}. If you transfer incomplete data, the “validation” field will display:

  • missing information
  • errors in your ad.

Sample request:

  curl -X POST \
  'https://api.allegro.pl/sale/offers' \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Content-Type: application/vnd.allegro.public.v1+json' \
  -d '{
    "name": "BMW X5 e53",                           -- required; ad title
    "category": {
        "id": "257150"                              -- required; category of the lowest tier
                                                    that hosts the offer. To retrieve category numbers
                                                    call GET /sale/categories?parent.id={categoryId}
   }
 }'
 
  
Click to view sample response:
{

  '{
    "id": "6206178738",
    "name": "BMW X5 e53",
    "category": {
        "id": "57968"
    },
    "parameters": [],
    "ean": null,
    "description": null,
    "compatibilityList": {
        "items": null
    },
    "images": [],
    "sellingMode": null,
    "stock": null,
    "publication": {
        "duration": null,
        "status": "INACTIVE",
        "startingAt": null,
        "endingAt": null
    },
    "delivery": null,
    "payments": {
        "invoice": "NO_INVOICE"
    },
    "afterSalesServices": null,
    "additionalServices": null,
    "sizeTable": null,
    "fundraisingCampaign": null,
    "promotion": null,
    "location": null,
    "external": null,
    "attachments": [],
    "contact": null,
    "validation": {
        "errors": [
            {
                "code": "VALIDATION_ERROR",
                "message": "Location may not be empty.",
                "details": "",
                "path": "",
                "userMessage": "Location may not be empty."
            },
            {
                "code": "VALIDATION_ERROR",
                "message": "Payments may not be empty.",
                "details": "",
                "path": "",
                "userMessage": "Payments may not be empty."
            },
            {
                "code": "VALIDATION_ERROR",
                "message": "Please describe your offer.",
                "details": "",
                "path": "",
                "userMessage": "Please describe your offer."
            },
            {
                "code": "VALIDATION_ERROR",
                "message": "Missing required parameters: Stan, Rok produkcji, Przebieg [km], Pojemność silnika [cm3], Liczba drzwi, Kolor, Uszkodzony.",
                "details": "",
                "path": "",
                "userMessage": "Missing required parameters: Stan, Rok produkcji, Przebieg [km], Pojemność silnika [cm3], Liczba drzwi, Kolor, Uszkodzony."
            },
            {
                "code": "VALIDATION_ERROR",
                "message": "You must select at least one selling mode and provide the required prices.",
                "details": "",
                "path": "",
                "userMessage": "You must select at least one selling mode and provide the required prices."
            },
            {
                "code": "VALIDATION_ERROR",
                "message": "After sales service conditions (return policies, implied warranties) are required by company account.",
                "details": "",
                "path": "",
                "userMessage": "After sales service conditions (return policies, implied warranties) are required by company account."
            }
        ],
        "validatedAt": "2019-02-26T11:33:38.599Z"
    },
    "createdAt": "2019-02-26T11:33:38Z",
    "updatedAt": "2019-02-26T11:33:38.6Z"
  }'
  

7. Data in the ad

Call PUT /sale/offers/{offerId} to complete data in the draft or listed ad. To publish the ad later, transfer a complete set of information. If you transfer incomplete data, the “validation” field will display:

  • missing information
  • errors in your ad.


Note! If you want to update an ongoing ad, retrieve its data by calling GET /sale/offers/{offerId}. Next, when you update the ad, transfer the complete data structure you have received earlier in the response. Even if you update only one field, you have to send the complete structure of ad fields.

Below you will find a list of fields that you need to fill in to list the ad. Use the other fields if you want to list an offer. For more information please refer to our guide.


Click to view sample request:
curl -X PUT \
  'https://api.allegro.pl/sale/offers/6206178738’ \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Content-Type: application/vnd.allegro.public.v1+json' \
  -d '{
    "id": "6206178738",                 -- ad identification number
    "name": "BMW X5 e53",               -- required; ad title
    "category": {
        "id": "57968"                   -- required; category of the lowest tier
                                        that hosts the offer. To retrieve category numbers
                                        call GET /sale/categories?parent.id={categoryId}
    },
    "parameters": [                     -- required; ad parameters; to check parameters
                                        available in the category call
                                        GET /sale/categories/{categoryId}/parameters
        {
            "id": "11323",
            "valuesIds": [
                "11323_2"
            ],
            "values": [],
            "rangeValue": null
        },
        {
            "id": "1",
            "valuesIds": [],
            "values": [
                "2003"
            ],
            "rangeValue": null
        },
        {
            "id": "4",
            "valuesIds": [],
            "values": [
                "370000"
            ],
            "rangeValue": null
        },
        {
            "id": "5",
            "valuesIds": [],
            "values": [
                "3000"
            ],
            "rangeValue": null
        },
        {
            "id": "14",
            "valuesIds": [],
            "values": [
                "189"
            ],
            "rangeValue": null
        },
        {
            "id": "12",
            "valuesIds": [
                "12_3"
            ],
            "values": [],
            "rangeValue": null
        },
        {
            "id": "128789",
            "valuesIds": [],
            "values": [
                "5"
            ],
            "rangeValue": null
        },
        {
            "id": "3",
            "valuesIds": [
                "3_246550"
            ],
            "values": [],
            "rangeValue": null
        },
        {
            "id": "178",
            "valuesIds": [
                "178_1"
            ],
            "values": [],
            "rangeValue": null
        }
    ],
    "ean": null,
    "description": {                    -- required; ad content; for more information on
                                        drafting correct ad description visit this page
        "sections": [
            {
                "items": [
                    {
                        "type": "TEXT",
                        "content":  "<p>opis tekstowy</p>"
                    }
                ]
            }
        ]
    },
    "compatibilityList": null,
    "images": [                         -- required image paths; send photos
                                        by calling: POST /sale/images.
                                        The first photo in the array
                                        is also the first ad photo (thumbnail)
        {
            "url": "https://a.allegroimg.allegrosandbox.pl/original/035b44/6932986c4333a35d8010bdd1993b"
        },
        {
            "url": "https://a.allegroimg.allegrosandbox.pl/original/03cea0/b7bff1db4deab57ad277891442aa"
        }
    ],
    "sellingMode": {
        "format": "ADVERTISEMENT",      -- required; sales format ADVERTISEMENT (classified ad)
        "price": {
            "amount": "33000",          -- required; price
            "currency": "PLN"
        },
        "startingPrice": null,
        "minimalPrice": null
    },
    "stock": null,
    "publication": {
        "duration": null,               -- always null; do not edit these values; they will
                                        change automatically after assigning a particular
                                        package and additional options after calling
                                        PUT /sale/offer-classifieds-packages/{offer-id}.
        "status": "INACTIVE",           -- offer status; two values are supported:
                                        ACTIVE (active ad), INACTIVE (inactive ad)
        "startingAt": null,             -- not required; ad start time, applies to
                                        scheduled offers
        "endingAt": null                -- not required, ad end time
    },
    "delivery": {
        "shippingRates": null,
        "handlingTime": null,
        "additionalInfo": null,
        "shipmentDate": null
    },
    "payments": {
        "invoice": "NO_INVOICE"         -- required; information on invoice;
                                        four values are supported: VAT (VAT invoice);
                                        VAT_MARGIN (VAT invoice margin);
                                        WITHOUT_VAT (invoice without VAT);
                                        NO_INVOICE (I dont issue invoices)
    },
    "afterSalesServices": null,
    "additionalServices": null,
    "sizeTable": null,
    "fundraisingCampaign": null,
    "promotion": null,                  -- always null; do not edit these values; they will
                                        change automatically after assigning a particular
                                        package and additional options after calling
                                        PUT /sale/offer-classifieds-packages/{offer-id}.
    "location": {                       -- required; information on location
        "countryCode": "PL",            -- required; country code according to
                                        ISO 3166-1 alpha-2
        "province": "WIELKOPOLSKIE",    -- required in the case of countryCode PL;
                                        province; supported values:
                                        DOLNOSLASKIE; KUJAWSKO_POMORSKIE;
                                        LUBELSKIE; LUBUSKIE; LODZKIE; MALOPOLSKIE; MAZOWIECKIE;
                                        OPOLSKIE; PODKARPACKIE; PODLASKIE; POMORSKIE; SLASKIE;
                                        SWIETOKRZYSKIE; WARMINSKO_MAZURSKIE; WIELKOPOLSKIE;
                                        ZACHODNIOPOMORSKIE. This value is not required
                                        in the case of other countries.
        "city": "Poznań",               -- required; city
        "postCode": "60-166"            -- required in the case of Polish addresses;
                                        postal code
    },
    "external": {                       -- not required; external ID / number
                                        assigned by the seller, e.g. to link the ad with
                                        a product in the sellers warehouse.
                                        You can provide a default string of characters
                                        that will be displayed after ad relisting.
        "id":"4131asdsad40011"                  
                },                              
    "attachments": [],
    "contact": {                        -- required; identifier of contact data;
                                        retrieve it by calling
                                        GET /sale/offer-contacts
        "id": "0c046252-9559-4ecb-8ea3-879f60e46947"
    },
    "validation": {         
        "errors": [],                   -- information on errors
        "validatedAt": "2019-02-26T11:33:38.599Z"   -- date of the most recent
                                                    ad validation
    },
    "createdAt": "2019-02-26T11:33:38Z",            -- ad creation date
    "updatedAt": "2019-02-26T11:33:38.6Z"           -- ad update date
}

Click to view sample response:
‘{
    "id": "6206178738",
    "name": "BMW X5 e53",
    "category": {
        "id": "57968"
    },
    "parameters": [
        {
            "id": "11323",
            "valuesIds": [
                "11323_2"
            ],
            "values": [],
            "rangeValue": null
        },
        {
            "id": "1",
            "valuesIds": [],
            "values": [
                "2003"
            ],
            "rangeValue": null
        },
        {
            "id": "4",
            "valuesIds": [],
            "values": [
                "370000"
            ],
            "rangeValue": null
        },
        {
            "id": "5",
            "valuesIds": [],
            "values": [
                "3000"
            ],
            "rangeValue": null
        },
        {
            "id": "14",
            "valuesIds": [],
            "values": [
                "189"
            ],
            "rangeValue": null
        },
        {
            "id": "12",
            "valuesIds": [
                "12_3"
            ],
            "values": [],
            "rangeValue": null
        },
        {
            "id": "128789",
            "valuesIds": [],
            "values": [
                "5"
            ],
            "rangeValue": null
        },
        {
            "id": "3",
            "valuesIds": [
                "3_246550"
            ],
            "values": [],
            "rangeValue": null
        },
        {
            "id": "178",
            "valuesIds": [
                "178_1"
            ],
            "values": [],
            "rangeValue": null
        }
    ],
    "ean": null,
    "description": {
        "sections": [
            {
                "items": [
                    {
                        "type": "TEXT",
                        "content":  "<p>opis tekstowy</p>"
                    }
                ]
            }
        ]
    },
    "compatibilityList": {
        "items": null
    },
    "images": [
        {
            "url": "https://a.allegroimg.allegrosandbox.pl/original/035b44/6932986c4333a35d8010bdd1993b"
        },
        {
            "url": "https://a.allegroimg.allegrosandbox.pl/original/03cea0/b7bff1db4deab57ad277891442aa"
        }
    ],
    "sellingMode": {
        "format": "ADVERTISEMENT",
        "price": {
            "amount": "33000",
            "currency": "PLN"
        },
        "startingPrice": null,
        "minimalPrice": null
    },
    "stock": null,
    "publication": {
        "duration": null,
        "status": "INACTIVE",
        "startingAt": null,
        "endingAt": null
    },
    "delivery": {
        "shippingRates": null,
        "handlingTime": null,
        "additionalInfo": null,
        "shipmentDate": null
    },
    "payments": {
        "invoice": "NO_INVOICE"
    },
    "afterSalesServices": null,
    "additionalServices": null,
    "sizeTable": null,
    "fundraisingCampaign": null,
    "promotion": null,
    "location": {
        "countryCode": "PL",
        "province": "WIELKOPOLSKIE",
        "city": "Poznań",
        "postCode": "60-166"
    },
    "external": {
        "id": "4131asdsad40011"
    },
    "attachments": [],
    "contact": {
        "id": "0c046252-9559-4ecb-8ea3-879f60e46947"
    },
    "validation": {
        "errors": [],
        "validatedAt": "2019-02-26T11:57:05.352Z"
    },
    "createdAt": "2019-02-26T11:33:38Z",
    "updatedAt": "2019-02-26T11:57:05.352Z"
  }’

8. Package and additional options

Assign previously selected package and additional options to a draft by calling PUT /sale/offer-classifieds-packages/{offer-id}, You must be logged in as the draft author.

Note! You can change packages only until the ad is published. Once the ad is active, you can add only promo options.

Sample request:

  
 {
  curl -X PUT \
  'https://api.allegro.pl/sale/offer-classifieds-packages/6206178738’ \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Content-Type: application/vnd.allegro.public.v1+json' \
  -d '{
    "basePackage": {
        "id": "3174be19-56f9-484b-b72c-43b0b00785e8"        -- identifier
    },
    "extraPackages": [{
            "id": "3174be19-56f9-484b-b72c-43b0b00785e8"    -- ID of additional options
                                                            you want to buy to the package
        },
        {
            "id": "3174be19-56f9-484b-b72c-43b0b00785e6"
        }
    ]
 }'
 

Sample response:

  
 Status 200 OK
 

9. Cost of ad listing

After you assign the package and the ad is ready to be published, call POST /pricing/offer-fee-preview to check the listing cost. In the body section provide the complete structure you have received after calling GET /sale/offers/{offerId} , as well as selected packages and additional options that you can download by GET /sale/offer-classifieds-packages/{offer-id}.


Click to view sample request:
curl -X POST \
‘https://api.allegro.pl/pricing/fee-preview’ \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Content-Type: application/vnd.allegro.public.v1+json'  \
-H 'Authorization: Bearer {token}' \
-H 'Accept-Language: PL' \
-d '{
    “offer”: {
    "id": "6206178738",
    "name": "BMW X5 e53",
    "category": {
    "id": "57968"
    },
    "parameters": [
        {
            "id": "11323",
            "valuesIds": [
                "11323_2"
            ],
            "values": [],
            "rangeValue": null
        },
        {
            "id": "1",
            "valuesIds": [],
            "values": [
                "2005"
            ],
            "rangeValue": null
        },
        {
            "id": "4",
            "valuesIds": [],
            "values": [
                "150000"
            ],
            "rangeValue": null
        },
        {
            "id": "5",
            "valuesIds": [],
            "values": [
                "3000"
            ],
            "rangeValue": null
        },
        {
            "id": "14",
            "valuesIds": [],
            "values": [
                "231"
            ],
            "rangeValue": null
        },
        {
            "id": "12",
            "valuesIds": [
                "12_3"
            ],
            "values": [],
            "rangeValue": null
        },
        {
            "id": "128789",
            "valuesIds": [],
            "values": [
                "5"
            ],
            "rangeValue": null
        },
        {
            "id": "3",
            "valuesIds": [
                "3_4"
            ],
            "values": [],
            "rangeValue": null
        },
        {
            "id": "178",
            "valuesIds": [
                "178_1"
            ],
            "values": [],
            "rangeValue": null
        }
    ],
    "ean": null,
    "description": {
        "sections": [
            {
                "items": [
                    {
                        "type": "TEXT",
                        "content":  "<p>opis tekstowy</p>"
                    }
                ]
            }
        ]
    },
    "compatibilityList": null,
    "images": [
        {
            "url": "https://a.allegroimg.allegrosandbox.pl/original/035b44/6932986c4333a35d8010bdd1993b"
        },
        {
            "url": "https://a.allegroimg.allegrosandbox.pl/original/03cea0/b7bff1db4deab57ad277891442aa"
        }
    ],
    "sellingMode": {
        "format": "ADVERTISEMENT",
        "price": {
            "amount": "33000",
            "currency": "PLN"
        },
            "startingPrice": null,
            "minimalPrice": null
            },
        "stock": null,
        "publication":
   {
        "duration": "PT720H",
        "status": "INACTIVE",
        "startingAt": null,
        "endingAt": null,
    },
    "delivery": {
        "shippingRates": null,
        "handlingTime": null,
        "additionalInfo": null,
        "shipmentDate": null
    },
    "payments": {
        "invoice": "NO_INVOICE"
    },
    "afterSalesServices": null,
    "additionalServices": null,
    "sizeTable": null,
    "fundraisingCampaign": null,
    "promotion": {
            "emphasized": false,
            "bold": true,
            "highlight": true,
            "departmentPage": false,
            "emphasizedHighlightBoldPackage": false
    },
    "location": {
        "countryCode": "PL",
        "province": "WIELKOPOLSKIE",
        "city": "Poznań",
        "postCode": "60-166"
    },
    "external": {
        "id":"4131asdsad40011"
                },
    "attachments": [],
    "contact": {
        "id": "0c046252-9559-4ecb-8ea3-879f60e46947"
    },
    "validation": {
        "errors": [],
        "validatedAt": "2019-02-26T11:33:38.599Z"
    },
    "createdAt": "2019-02-26T11:33:38Z",
    "updatedAt": "2019-02-26T11:33:38.6Z",
    },
    “classifiedsPackages”: {
        “basePackage”: {
            "id": "708a5240-0dc4-4573-8d50-4a32cdcc5823”
        },
        “extraPackages”: [{
            "id": "74bb1eef-28d3-443a-91ed-d39b0646f2c3"
        },
        {
            "id": "45d1d9d2-0696-4326-9dd0-8d02120f8a1c"
        }]}
    }

Click to view sample response:
'{
    "commissions": [],
    "quotes": [,
        {
            "name": "Opłata za pakiet Power",
            "fee": {
                "amount": "39.00",
                "currency": "PLN"
            }
            "cycleDuration": "PT1200H"
            "classifiedsPackage": {
                "id":"708a5240-0dc4-4573-8d50-4a32cdcc5823"
                    }
        },
        {
            "name": "Opłata za wyróżnienie ogłoszenia",
            "fee": {
                "amount": "39.00",
                "currency": "PLN"
            }
            "cycleDuration": "PT240H"
            "classifiedsPackage": {
                "id":"74bb1eef-28d3-443a-91ed-d39b0646f2c3"
                    }
        },
        {
            "name": "Promowanie na stronie działu - ogłoszenie",
            "fee": {
                "amount": "33.00",
                "currency": "PLN"
            }
            "cycleDuration": "PT120H"
            "classifiedsPackage": {
                "id":"45d1d9d2-0696-4326-9dd0-8d02120f8a1c"
                    }
        },
        }
  ...
    ]
  }'

10. Publish your ad

Once the ad is complete and properly validated, call PUT /sale/offer-publication-commands/{commandId} to publish the ad on the site. The publication process is asynchronous. In commandId provide the value in the UUID (universally unique identifier) format. It is a unique identifier that consists of 32 hexadecimal numbers (e.g. 21ae4ed1-eab7-34ea-b605-cf2e22b5eed3).


Note! Use this method to:

  • end particular ads, by providing END in the action field
  • schedule ads, by providing the listing date in the scheduleFor field
  • relist your ad by transferring “ACTIVATE” in the action field. As a result, the ad will be relisted.
information

Before relisting ad it is necessary to assign the package and additional options again. At the same time, we will charge fees for selected package and additional options again.

Sample request:

  
   curl -X PUT \
  'https://api.allegro.pl/sale/offer-publication-commands/3380d97f-0d32-4747-8a17-1da38f9499de’ \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Content-Type: application/vnd.allegro.public.v1+json' \
  -d '{
    "publication": {
        "action": "ACTIVATE",               -- required; two values are supported:
                                            ACTIVATE (ad activating) and
                                            END (ad ending)
"scheduledFor":"2018-03-28T12:00:00.000Z"   -- not required; send if you want
                                            to schedule listing of your ad
    },
    "offerCriteria": [
        {
            "offers":[                      -- required; array of objects with
                                            offer IDs
                {
                    "id": "7276377308"
                }
            ],
            "type": "CONTAINS_OFFERS"       -- required; at present only one
                                            value is supported:
                                            CONTAINS_OFFERS
                                            (ads whose status is subject to change)
     }
    ]
  }’
  


Note! The response will contain an empty summary. We are not able to verify immediately the number of offers that will be published correctly. To check the task status, use one of the dedicated methods described in the next step.

Sample response:

  
   ‘{
    "id": "3380d97f-0d32-4747-8a17-1da38f9499de",
    "taskCount": {
        "total": 0,
        "success": 0,
        "failed": 0
    }’
  

11. Ad listing status

To check the status of a task you ordered in the previous step call:

Summary of ad listing

GET /sale/offer-publication-commands/{commandId} - you will receive a summary with a number of correctly listed ads and errors.
Sample request:

  
   curl -X GET \
  'https://api.allegro.pl/sale/offer-publication-commands/{commandId}’ \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json'
  

Sample response:

  
  '{
    "id": "3380d97f-0d32-4747-8a17-1da38f9499de",
    "taskCount": {
        "total": 1,
        "success": 1,
        "failed": 0
    }
   }'
  

Information on ad statuses

GET /sale/offer-publication-commands/{commandId}/tasks - use this resource to retrieve information on ad statuses. The response will contain:

  • IDs of ads you wanted to list on the site
  • ad editing status – whether it was successful
  • date of ad editing order
  • date of order execution – listing or ending an ad
  • in the case of FAIL status – information about the error reasons in the “message” field

Sample request:

  
  curl -X GET \
  'https://api.allegro.pl/sale/offer-publication-commands/{commandId}/tasks’ \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json'
  

Przykładowy resposne:

  
  ‘{
            "offer": {
                "id": "7168735300"
            },
            "message": "",                      -- explanation why it failed to list the ad
            "status": "SUCCESS",                -- ad listing status; three values are supported:
                                                SUCCESS (listing was successful);
                                                FAIL (errors have occurred and the ad is inactive);
                                                NEW (listing in progress;
                                                the action is not complete yet)
            "scheduledAt": "2018-03-01T11:02:50.005+01:00",
            "finishedAt": "2018-03-01T11:02:51.691+01:00",
            "field": "publication"
      }’
  

Managing classified ads

1. Additional promo options

Note! You can change packages only until the ad is published. Once the ad is active, you can add only promo options Use the following REST API resources to manage additional promo options in ongoing ads:

  • GET /sale/offer-classifieds-packages/{offer-id} - retrieve information on a package and additional options assigned to the ad,
  • PUT /sale/offer-classifieds-packages/{offer-id} - buy additional options.

Promo options assigned to ad

GET /sale/offer-classifieds-packages/{offer-id} - use this resource to retrieve information on a package and additional options assigned to the ad. You must be logged in as a user who listed the ad.ogłoszenie.


Sample request:

  
  curl -X GET \
  'https://api.allegro.pl/sale/offer-classifieds-packages/{offer-id}’ \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json
  

Sample response:

  
  ‘{
    "basePackage": {
        "id": "3174be19-56f9-484b-b72c-43b0b00785e8"
    },
    "extraPackages": [{
            "id": "3174be19-56f9-484b-b72c-43b0b00785e8"
        },
        {
            "id": "3174be19-56f9-484b-b72c-43b0b00785e6"
        }
    ]
  }’
  

Editing of promo options

PUT /sale/offer-classifieds-packages/{offer-id} - Use this resource to buy additional promo options. Apart from additional options you want to add, transfer the structure you have retrieved by calling GET /sale/offer-classifieds-packages/{offer-id}. You must be logged in as a user who listed the ad.

Sample request:

  
  curl -X PUT \
  'https://api.allegro.pl/sale/offer-classifieds-packages/{offer-id}’’ \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Content-Type: application/vnd.allegro.public.v1+json'
  -d '{
    "basePackage": {
        "id": "3174be19-56f9-484b-b72c-43b0b00785e8"
    },
    "extraPackages": [{
            "id": "3174be19-56f9-484b-b72c-43b0b00785e8"
        },
        {
            "id": "3174be19-56f9-484b-b72c-43b0b00785e7"
        },
        {
            "id": "3174be19-56f9-484b-b72c-43b0b00785e6"
        }
    ]
  }'
  

Sample response:

  
  Status 201 No Content
  

2. Editing ad data

If you want to edit data in your ad, retrieve it by calling GET /sale/offers/{offerId}. And transfer the whole structure you will receive in the response by using PUT /sale/offers/{offerId}. Remember to change the data in fields you want to edit before sending the request. You must be authenticated and authorized as a seller that listed the ad in question.

WAŻNE! Note! Even if you want to change one field, you must transfer the whole structure you have retrieved by calling GET /sale/offers/{offerId}.

Listing a similar ad

If you have listed an ad and want to list a similar one, retrieve it by calling GET /sale/offers/{offerId}. Call GET /sale/offers/{offerId} to retrieve all fields of the particular ad. You must be authenticated and authorized as a seller that listed the ad in question. The whole structure apart from:

  • id - ad identification number,
  • validatedAt - information on most recent ad validation,
  • createdAt - ad creation date,
  • updatedAt - ad update date.

transfer by calling POST /sale/offers. Therefore, you will create a new draft based on data of the retrieved ad. Once you complete the draft, you can edit the structure retrieved by calling GET /sale/offers/{offerId}.

List of resources

Full documentation of resources in the swagger.yaml form file you will find here.

List of basic resources used in tutorial:

List of supporting resources used in tutorial: