Listing offers through Allegro REST API

Offer model

1. Prepare a draft

Use POST /sale/offers to create offer drafts. The draft does not have to be a complete ready-to-publish offer. You can finish it up later. You can complete the draft with more information by using PUT /sale/offers/{offerId}. Use the drafts to:

  • store the offer data on our servers,

  • prepare an offer preview.


2. Associate your offer with a product

In 2019, we have introduced the Allegro Product Catalog in selected categories. Within Allegro Product Catalog we want to gather and describe all of the products that are available in the sellers listed offers. We catalog individual products as a representative, which differs from others with their properties, e.g. model, manufacturer’s code, GTIN number or other basic parameters.

Currently, part of your offers must be associated with the Allegro Product Catalog. By the end of 2021 we want to catalog all offers in categories where it is possible.

You can find more information on how to assign a product to your offer in point 4. Productization.


3. List an offer

You can activate a complete draft (with an INACTIVE status) if no errors are displayed in the “validation” section. The offer is validated every time you edit it. If you send changes that contain:

  • incorrect data, identifier, etc. – status 422 will be returned,
  • logic errors that block the listing process, e.g. missing reserve price in the case of an auction – a proper error message will be displayed in the “validation” section.

If there are no errors, you can publish the draft on Allegro.pl. To activate the draft, perform ACTIVATE on PUT /sale/offer-publication-commands/{commandId}. Until your offer is published on Allegro, it will have an ACTIVATING status. The same status is applied to offers with a scheduled listing date.

You can find more information on how to publish an offer in point 13. Offer publication.


4. Check an offer status

Once the offer is listed, its status will be changed to ACTIVE. The exact listing date is displayed in the scheduledAt field, use the GET /sale/offer-publication-commands/{commandId}/tasks command to bring it up. Use the same method to close an offer by performing the END command.


Note! All requests must be executed with an OAuth 2.0 token

1. Offer draft

Use POST /sale/offers. You must be an authenticated and authorized user. Once the draft offer is created, you can publish it later on the site. You can transfer partial data (at least the title) and then complete the draft via PUT /sale/offers/{offerId}. If you transfer incomplete data, the “validation” field will display:

  • missing information,
  • errors in your offer.
information You can create up to 20,000 drafts. When you exceed the limit, you will not be able to add new drafts and will receive the following message - “You cannot create new drafts - your account has exceeded the maximum number 20,000 of drafts.”. Delete unnecessary with DELETE /sale/offers/{offerId}. The offer draft is stored for 60 days. After that, the offer draft will be deleted. If you edit something in the offer draft, we will extend its validity by 60 days.

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": "Oferta testowa"                        -- required, offer title
  }

Click to view sample response:
{
    "id": "7276377308",
    "name": "Oferta testowa",
    "category": null,
    "parameters": [],
    "description": null,
    "images": null,
    "sellingMode": null,
    "tax": null,
    "stock": null,
    "publication": {
        "republish": null,
        "duration": null,
        "status": "INACTIVE",
        "startingAt": null,                         – value in response
                                                    always returns null
        "endingAt": null
    },
    "delivery": null,
    "payments": {
        "invoice": "NO_INVOICE"
    },
    "discounts": null,
    "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": "New offer description is required.",
                "details": "",
                "path": "",
                "userMessage": "New offer description is required."
            },
            {
                "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": "Category may not be empty.",
                "details": "",
                "path": "",
                "userMessage": "Category may not be empty."
            },
            {
                "code": "VALIDATION_ERROR",
                "message": "Describe your offer.",
                "details": "",
                "path": "",
                "userMessage": "Describe your offer."
            }
        ],
        "validatedAt": "2018-04-06T09:29:47.544Z"
    },
    "createdAt": "2018-04-06T09:29:47Z",
    "updatedAt": "2018-04-06T09:29:47.544Z"
}

2. Offer title

Offer title is provided in the name field, we allow a maximum of 50 characters in the offer title. These are the letters, numbers, and special characters allowed in offer titles.

	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 characters:'!','@','[',']','#','$','%','^','&','*','{','}','(',')','.',',','/','\\','|','?',' ',';','~','²','³',
	'`','\'','’','´','\"','”','"','„','“','″','<','>','_','\t',':','-','=','+','0','…','–','°','°'
Note! Some letters and special characters are converted to entities, therefore they take more than one character. For example the “&” is represented as &amp; and so takes up 5 characters.

3. Category and parameters

Use the resources below to retrieve identifiers of the selected category and parameters - complete the data in the category and parameters sections.

Category IDs

Use GET /sale/categories?parent.id={categoryId} to retrieve a list of subcategories that belong to the category provided as parent.id parameter.

Note!

  • If you use GET /sale/categories without providing any category, you will retrieve IDs of main Allegro categories. Use the identifiers to get to the lowest tier category.

  • Remember – an offer can be listed in the lowest tier category if the category is marked “leaf”: true.

  • We highly recommend assigning offers to products. The feature is available in selected categories in which we group offers presenting the same product. You will receive product data only in particular categories The categories are marked with “offersWithProductPublicationEnabled”: true.

Sample request:

  curl -X GET \
    'https://api.allegro.pl/sale/categories?parent.id={categoryId}
    -H 'Accept: application/vnd.allegro.public.v1+json' \
	-H 'Accept-Language: en-US'
    -H 'Authorization: Bearer {token}'
Sample response:
 {
  "categories":[
  {
   "id": "348",        							-- category ID
   "name": "GSM Accessories",     				-- category name
   "parent": {         							-- parent category ID; in the case of main
                                                categories, the value is null
   },
   "leaf": false,        						-- whether the category is
                                                of the lowest tier;
   "options": {        							-- category features
    "advertisement": false,     				-- whether the category
                                                or its subcategory supports classified ads.
    "advertisementPriceOptional": false,  		-- whether a price is optional in
                                                the classified ad category.
    "offersWithProductPublicationEnabled": true, -- whether the category
                                                 supports assigning offers to a product.
	"productCreationEnabled": false,			-- whether the category
                                                supports creating a product.
	"customParametersEnabled": true             -- whether the category supports
												custom parameters
	}
  }]
 }

Parameters

Use GET /sale/categories/{categoryId}/parameters to retrieve the lists of parameters that are supported by the category.id you indicated. Every time a list of parameters supported by the input category is returned.

Sample request:

  curl -X GET \
    'https://api.allegro.pl/sale/categories/{catId}/parameters
    -H 'Accept: application/vnd.allegro.public.v1+json' \
	-H 'Accept-Language: en-US' \
    -H 'Authorization: Bearer {token}' \
Click to view sample response:
{
    "parameters": [                         – list of parameters supported
                                               by the particular category
    {
        "id": "11323",                      – unique parameter ID
        "name": "Condition",                – parameter name
        "type": “dictionary”,               – parameter type; supported values: dictionary
                                              (of single or multiple choice, depending on
                                              the value of multipleChoices), integer and float,
                                              string (you can add one or more value)
        "required":true,                    – information whether a particular parameter
                                               is required; two values are supported:
                                               true (yes) and false (no)
        "unit": null,
        "requiredForProduct": true          – whether you need to provide value for this
                                            parameter when you create a new product
        "options": {
            "variantsAllowed": false,
            "variantsEqual": false
            "ambiguousValueId": "216917_41" – identifier for ambiguous value,
                                            e.g. "other"
            "dependsOnParameterId": null    – values in the dictionary depend on the
                                            parameter referenced by this field.
            "requiredDependsOnValueIds": [  – values identifier of the
                                            conditioning parameter, which determines
            "202870_1"                      whether a parameter will be require
            ],
            "displayDependsOnValueIds": [   –  set of values identifiers of the
                                            conditioning parameter, which determines
            "202870_1",                     whether a parameter will be visible
            "202870_2"
            ],
            "describesProduct": true,       – whether the parameter describe product
            "customValuesEnabled": false    – whether you can add your own value for
                                            a parameter with an ambiguous value
        },
        "dictionary": [
            {
                "id": "11323_1",
                "value": "New",
                "dependsOnValueIds": []
            },
            {
                "id": "11323_2",
                "value": "Used",
                "dependsOnValueIds": []
            }
        ],
        "restrictions": {
        "multipleChoices": false            – this parameter enables choosing
                                               one or more values; supported values:
                                               true (yes) and false (no)
        }
    },
    {
        "id": "211966",
        "name": "Cutting Height Range Adjustment",
        "type": "float",
        "required": false,
        "unit": null,
        "requiredForProduct": true
        "restrictions": {
            "min": 0,
            "max": 1000,
            "range": true,              – range parameter; provide
                                        minimum and maximum value
            "precision": 2
            }
        },
    {
        "id": "17448",
        "name": "Weight (with packaging)",
        "type": "float",
        "required":false,
        "restrictions": {
            "min": 5,
            "max": 10,
            "range": true,                  – range parameter. Sections range min
                                               and max define the minimum and maximum
                                               value of a parameter
            "precision": 3                  – defines the number of decimals
                                               in this case – three decimal places
        }
    },
    {
        "id": "216917",
        "name": "Included accessories",
        "type": "string",
        "required": false,
        "unit": null,
        "requiredForProduct": false
        "options": {
            "variantsAllowed": false,
            "variantsEqual": false,
            "ambiguousValueId": "216917_41", – identifier for ambiguous value,
                                            e.g. "other"
            "dependsOnParameterId": null,
            "describesProduct": false,
            "customValuesEnabled": false
        },
        "restrictions": {
            "minLength": 1,
            "maxLength": 40,
            "allowedNumberOfValues": 10     – information on how many values
                                            you can enter in a given parameter
        }
    }
    ]
}

information Note! You should always check and update the parameters, especially the dictionary type parameter, because their values may change in time.

Below you can find samples of properly completed sample parameter structures, depending on their type:

  • for dictionary parameter type (one value or more values)

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

  • for range parameter type

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

  • for string parameter type

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

Custom parameters

Optionally, you can fill your own parameters in selected categories. Use GET /sale/categories/{categoryId} and check value in customParametersEnabled to verify if it is possible.

Custom parameters:

  • must be added in customParameters field in the offer model. The parameter will be visible on the offer page.
  • have the same limit as in the sales form on the website - you can add up to 4 custom parameters for which you can provide one value,
  • can’t be duplicates - if parameters with this name already exist in Allegro, we will return an appropriate error. However, you can add custom parameters with the same name to the different offers.

Sample request structure:

   {
   ...
   "parameters": [...],
   "customParameters": [
    {
      "name": "Name of your own parameter",
      "values": [
        "Value of your own parameter"
      ]
    }
   ],
   "description": {...},
   ...}

Sample response structure:

   {
   ...
   "parameters": [...],
   "customParameters": [
    {
      "name": "Name of your own parameter",
      "values": [
        "Value of your own parameter"
      ]
    }
   ],
   "description": {...},
   ...}

Custom parameter values

You can define custom value for parameters with ambiguous value in selected categories. Use this option if you do not find the appropriate parameter value. Ambiguous parameter values are values like “other”, for example ““other” in the “Brand” parameter. You can retrieve its identifier via GET /sale/categories/{categoryId}/parameters field in options section - field ‘ambiguousValueId’.

To add your own value:

  {
    "parameters": [
      {
        "id": "129033",
        "name": "Brand",
        "type": “dictionary”,
        "required":true,
        "unit": null,
		"requiredForProduct": true
        "options": {
            "variantsAllowed": false,
            "variantsEqual": false,
            "ambiguousValueId": "129033_13"      	-- identifier for ambiguous value,
                                                    in this case it is “other”
		    "dependsOnParameterId": null,
	        "describesProduct": true,
            "customValuesEnabled": true             -- whether in the given parameter 
                                                    you can add your own value;
        },
        ...
   }
 {
    	"id": "129033",     				        -- parameter id
    	"valuesIds": [
     	 "129033_13"               					-- ambiguous value id
    	],
    	"values": [ "Missing brand name" ],	        -- value, which you want to provide.
													Complete this field.
    	"rangeValue": null
  }

4. Productization

Since 2019, we have been grouping offers presenting the same product. As a result, it is easier for the customers to find the product that meets their needs.

Currently, part of your offers must be associated with the Allegro Product Catalog. By the end of 2021 we want to catalog all offers in categories where it is possible.

In our guide - Assigning offers to a products, you will find detailed information on how to:

  • find a product in our catalog;
  • retrieve product data;
  • manage product in offer;
  • add product to our database.

You can also resign from listing offers via POST /sale/offers and instead use POST /sale/product-offers. Owing to it, you can list with one request

  • an active offer assigned to a product, which already exists in our database. Provide in your request EAN code (or product ID), price and quantity.
  • an active offer assigned to a product, which is not in our database. Provide in your request (in product object), product data which describe your product.

If, based on the data provided, we recognize that the product is in our database, we will take its data and include it in your offer.

You will find more information about using POST /sale/product-offers in our guide,

5. Images

Use POST /sale/images to upload images to our servers and receive suitable links using HTTP and HTTPS protocols (only with a valid certificate) . Important! More information about the rules for images in the gallery and description you will find here. You can choose from two options:

  • with a link Note! Remember to enter the domain address, do not use IP address.
      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"       -- required, image link
          }'

  • in a 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"				-- required, content of the
                                                           image file in a binary format

Sample response:

  • 401 - unauthorized

  • 413 - image is too large

  • 415 - incorrect image type

  • 201 - image uploaded correctly, response body:

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

6. Offer description

For more information on rules concerning offers please refer to the Seller page.

Note

  • the maximum size of the entire description is 40000 bytes

  • you can use only the following HTML tags:

    • h1 - title

    • h2 - subtitle

    • p - paragraph

    • ul - unordered (bulleted) list

    • ol - ordered list

    • li - list item

    • b - bold

  • in description you can use only images that are saved 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 offer via GET /sale/offers/{offerId}. This is the easiest way to learn how to prepare a correct description.

Structure of an offer 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"
        	}]
    	}]
	}

7. Delivery information

Shipping price list

You can create Shipping price using POST /sale/shipping-rates or via our website.

First, use GET /sale/delivery-methods to retrieve IDs and names of delivery options offered by Allegro. Use them to create a new shipping price list.

Sample request:

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

Click to view sample response:
{

"deliveryMethods": [ { "id": "7203cb90-864c-4cda-bf08-dc883f0c78ad", – general shipping method ID "name": "Przesyłka kurierska", – general shipping method name "paymentPolicy": "IN_ADVANCE", – payment policy, two values are supported: IN_ADVANCE and CASH_ON_DELIVERY "allegroEndorsed": false, – Allegro signed delivery, this field allows you to distinguish similar delivery methods with various restrictions, e.g. Allegro Paczkomaty 247 InPost from Paczkomaty 247 "shippingRatesConstraints": { "allowed": true, – if delivery method can be used when adding or modifying shipping rates "maxQuantityPerPackage": { – rules for the quantity per parcel "max": 999999 }, "firstItemRate": { – rules for the shipping cost for the first item in the parcel "min": "0.00", "max": "100000000.00", "currency": "PLN" }, "nextItemRate": { – rules for the shipping cost of another item in the parcel "min": "0.00", "max": "100000000.00", "currency": "PLN" }, "shippingTime": { – rules for the shipping time "default": { "from": "PT24H", "to": "PT48H" }, "customizable": true – if custom shipping time can be set when adding or modifying shipping rates } } }, { "id": "aa1d05e0-943b-47cb-a759-9d8c16707129", "name": "Allegro Przesyłka polecona", "paymentPolicy": "IN_ADVANCE", "allegroEndorsed": true, "shippingRatesConstraints": { "allowed": true, "maxQuantityPerPackage": { "max": 999999 }, "firstItemRate": { "min": "0.00", "max": "5.90", "currency": "PLN" }, "nextItemRate": { "min": "0.00", "max": "0.00", "currency": "PLN" }, "shippingTime": { "default": { "from": "PT96H", "to": "PT120H" }, "customizable": false } } }, … { "id": "845efe05-0c96-47c3-a8cb-aa4699c158ce", "name": "Przesyłka kurierska pobranie", "paymentPolicy": "CASH_ON_DELIVERY", "allegroEndorsed": false, "shippingRatesConstraints": { "allowed": true, "maxQuantityPerPackage": { "max": 999999 }, "firstItemRate": { "min": "0.00", "max": "100000000.00", "currency": "PLN" }, "nextItemRate": { "min": "0.00", "max": "100000000.00", "currency": "PLN" }, "shippingTime": { "default": { "from": "PT24H", "to": "PT48H" }, "customizable": true } } } ] }


If you have an offer without a shipping rate assigned, you can use GET /sale/offers/{offerId}/shipping-rates, to get delivery methods used in that offer.

Sample request

  curl -X GET \
  'https://api.allegro.pl/sale/offers/8151913057/shipping-rates' \
   -H 'Accept: application/vnd.allegro.beta.v1+json’
Sample response:
  {
    "rates": [
        {
            "deliveryMethod": {
                "id": "845efe05-0c96-47c3-a8cb-aa4699c158ce"	-- shipping method ID
            },
            "maxQuantityPerPackage": 1,							-- quantity per parcel
            "firstItemRate": {									-- shipping cost
                "amount": "11.00",
                "currency": "PLN"
            },
            "nextItemRate": {									-- shipping price of
                                                                another item in the parcel
                "amount": "0.00",
                "currency": "PLN"
            },
            "shippingTime": {                                   --  shipping time
                "from": "PT72H",
                "to": "PT120H"
            }
        }
    ]
 }

Now use POST /sale/shipping-rates to create a shipping price list. Use the shipping price list ID when creating an offer - in the shippingRates.id.

Note! You can have up to 250 shipping price lists saved to your account.

Click to view sample request:
curl -X POST \
  https://api.allegro.pl/sale/shipping-rates \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Authorization: {token}' \
  -H 'Content-Type: application/vnd.allegro.public.v1+json' \
  -d '{
    "name": "Nowy cennik dostawy",                              -- required, shipping price list name
    "rates": [
        {
            "deliveryMethod": {
                "id": "845efe05-0c96-47c3-a8cb-aa4699c158ce"    -- required, shipping method ID
            },
            "maxQuantityPerPackage": 10,                        -- required, quantity per parcel
            "firstItemRate": {                                  -- required, shipping cost
                "amount": "12.58",
                "currency": "PLN"
            },
            "nextItemRate": {                                   -- required, price for another
                                                                item in the parcel
                "amount": "12.58",
                "currency": "PLN"
            },
            "shippingTime": {                                   -- hipping time; it can be set only
                                                                for some delivery methods (e.g. "845efe05-0c96-47c3-a8cb-aa4699c158ce"),
                                                                and if it is not set, the default shipping time
                                                                for the delivery method will be used.
                "from": "PT72H",                                a multiple of 24,
                "to": "PT120H"                                  according to ISO 8601
                "from": "PT72H",
                "to": "PT120H"
            }
        },
        {
            "deliveryMethod": {
                "id": "2488f7b7-5d1c-4d65-b85c-4cbcf253fd93"
            },
            "maxQuantityPerPackage": 1,
            "firstItemRate": {
                "amount": "7.99",
                "currency": "PLN"
            },
            "nextItemRate": {
                "amount": "0.00",
                "currency": "PLN"
            }
        }
    ]
}'

Click to view sample response:
{
 "id": "73491425-dea3-420b-b2bb-680310d764e4",
    "name": "Nowy cennik dostawy",
    "rates": [
        {
            "deliveryMethod": {
                "id": "845efe05-0c96-47c3-a8cb-aa4699c158ce"
            },
            "maxQuantityPerPackage": 10,
            "firstItemRate": {
                "amount": "12.58",
                "currency": "PLN"
            },
            "nextItemRate": {
                "amount": "12.58",
                "currency": "PLN"
            },
            "shippingTime": {
                "from": "PT72H",
                "to": "PT120H"
            }
        },
        {
            "deliveryMethod": {
                "id": "2488f7b7-5d1c-4d65-b85c-4cbcf253fd93"
            },
            "maxQuantityPerPackage": 1,
            "firstItemRate": {
                "amount": "7.99",
                "currency": "PLN"
            },
            "nextItemRate": {
                "amount": "0.00",
                "currency": "PLN"
            },
            "shippingTime": null
        }
    ],
    "lastModified": "2018-04-03T13:46:54.722Z"
}


To check details of a particular shipping price list use GET /sale/shipping-rates/{shippingRatesId}.

Sample request:

  curl -X GET \
  https://api.allegro.pl/sale/shipping-rates/fde5853c-01ce-4991-a4b3-994c1a4a408e\
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Authorization: Bearer {token}'
Click to view sample response:
{
    "id": "ed1645ab-0895-4010-bd85-bb5d92ab0d83",               – shipping price list ID
    "name": "Cennik dostawy test API 1",                        – shipping price list name
    "rates": [
        {
            "deliveryMethod": {
                "id": "9081532b-5ad3-467d-80bc-9252982e9dd8"    – shipping method ID
            },
            "maxQuantityPerPackage": 1,                         – quantity per parcel
            "firstItemRate": {                                  – shipping cost
                "amount": "10.95",
                "currency": "PLN"
            },
            "nextItemRate": {                                   – shipping price of
                                                                another item in the parcel
                "amount": "0.00",
                "currency": "PLN"
            },
            "shippingTime": {                                   – shipping time,
                "from": "PT72H",                                a multiple of 24,
                "to": "PT120H"                                  according to ISO 8601
            }
        },
        {
            "deliveryMethod": {
                "id": "574d1c9e-9903-4626-903f-f72441d520d5"
            },
            "maxQuantityPerPackage": 1,
            "firstItemRate": {
                "amount": "8.60",
                "currency": "PLN"
            },
            "nextItemRate": {
                "amount": "0.00",
                "currency": "PLN"
            },
            "shippingTime": null
        }
    ],
    "lastModified": "2018-08-08T08:24:56.086Z"                  – last update of
                                                                the shipping price list
}

Read this article to learn how to manage shipping price lists linked to a seller account and offers.

Delivery settings

Retrieve it via GET /sale/delivery-settings.

Sample request:

  curl -X GET
  https://api.allegro.pl/sale/delivery-settings
  -H 'Authorization: Bearer {token}'
  -H 'Accept: application/vnd.allegro.public.v1+json'
  -H 'Content-Type: application/vnd.allegro.public.v1+json'
Sample response:
  {
  	"freeDelivery": {
    	"amount": 4.04,				-- minimum total order
        "currency": "PLN"           amout required for free delivery
   	},
   	"joinPolicy": {
    	"strategy": "MAX"			-- policy of calculating delivery costs
    },
	"customCost": {
    	"allowed": true				-- whether the custom delivery cost
                                    should be available
   },
   "updatedAt": "2019-08-21T10:13:40.036Z"
  }

You can edit delivery settings via PUT /sale/delivery-settings.

8. Offer terms

Provide information about warranty, return policy and complaints policy in the afterSalesServices. You can retrieve identifiers using:

Sample of a correctly completed structure:

  ...
    "afterSalesServices": {
        "impliedWarranty": {                                  -- complaints policy
            "id": "1377b0a6-b397-4e1e-b57c-4234bd84d036"
        },
        "returnPolicy": {				  -- return policy
            "id": "e261d4ed-ced7-4c10-82cd-13aa26192895"
        },
        "warranty": {				-- warranty information
            "id": "h2dsd4ed-ced7-2c10-82cd-13aa26192895"
        }
    },
  ...

9. Invoice settings and tax rate

Invoice settings

To specify whether and in what form the vendor provides VAT invoice, use the payments.invoice field and provide one of the available values:

  • VAT - VAT invoice,
  • VAT_MARGIN - VAT-margin invoice,
  • WITHOUT_VAT - invoice without VAT,
  • NO_INVOICE - no invoice.

Sample of a correctly completed structure:

  ...
  "payments": {
    "invoice": "NO_INVOICE"
  }
  ...  

Tax rate

You can specify a VAT rate in the offer, regardless of the selected invoice option.

You can check the available settings and identifiers of VAT rates in a given category by using GET /sale/tax-settings?category.id={categoryId}.

information Note! In each category, the available VAT settings may differ. Therefore, check what VAT rates are available for the given category.

To set a selected rate:

  • pass the appropriate combination of values for the tax.rate, tax.subject and tax.exemption fields, based on which we find the identifier of the matching VAT setting. If there is no match, we will return a validation error with information about which fields should be filled or a message that there is no match at all:
  ...
  "tax": {
    "rate": "23.00",
    "subject": "GOODS",
    "exemption": "MONEY_EQUIVALENT"
  }
  ...
  ...
  "tax": {
    "id": “f40ae51c-70a2-4882-98a7-6272404f0ec5”
  }
  ...

10. Promo options

You can manage offer promo options using our new resources, you can read more about them in our guide - How to manage offers. Owing to them sellers can easily manage the offer promo options - they can react faster to changes in sales and promote offers only when they consider it profitable.

Promotion of the offer is optional, you can also provide those information in the offer draft,

Sample of a correctly completed structure:

  ...
   "promotion": {   
        "emphasized": true,                                	
        "bold": false,                                    -- available only within 
                                                          emphasizedHighlightBoldPackage
        "highlight": false,                               -- available only within 
                                                          emphasizedHighlightBoldPackage
        "departmentPage": false,                          -- offer promoted on a category page
        "emphasizedHighlightBoldPackage": false           -- promo package: emphasized, 
                                                          highlighting and bold
    },
 ...

11. Additional options

Offer tags

If you have subscription enabled, you can assign tags to your published offer. However, first check the tags you have saved to your account.

information Note! On 1.04.2021 we reduced the limit of offer tags, which you can add to your account via: POST /sale/offer-tags. The current limit which was: 10000, has been changed to: 100. However, we did not remove redundant tags for users who have already exceeded the threshold of 100 tags.

You can retrieve the offer tags via: GET /sale/offer-tags. You will receive max 100 tags assigned to your account. You can also retrieve a list of tags that is adjusted to your needs owing to the following parameters:

  • offset - define a starting point for retrieving another batch of data (takes values from a scope that is covered by the integer data type). 0 by default.
  • limit - define a number of tags to be returned (takes values from a scope that is covered by the integer data). 100 by default.

e.g. GET /sale/offer-tags&offset=0&limit=10 will return a list of 10 tags starting with the first one.

Sample request:

  curl -X GET \
    http://api.allegro.pl/sale/offer-tags \
    -H 'Accept: application/vnd.allegro.public.v1+json' \
    -H 'Authorization: Bearer {token}
Sample response
  {
    "tags": [
        {
            "id": "500fedd3-2140-4225-87d4-a22484222776",   -- tag ID,
            "name": "Komiksy",                              -- tag name,
            "hidden": false                                 -- whether the tag is hidden –
                                                            false (displayed) or true (hidden),
        },
        {
            "id": "d2d2d475-7049-493d-bb95-f4ea59983ecb",
            "name": "Filmy",
            "hidden": false
        },
        {
            "id": "4b876428-d827-492b-a30e-aee3f5be791a",
            "name": "Muzyka",
            "hidden": false
        }
    ]
  }

Once you know which tags you want to use assign selected tags to your offer via POST sale/offers/{offerId}/tags.

Sample request:

  curl -X POST \
    http://api.allegro.pl/sale/offers/{offerId}/tags \
    -H 'Content-Type: application/vnd.allegro.public.v1+json'
    -H 'Accept: application/vnd.allegro.public.v1+json' \
    -H 'Authorization: Bearer {token}' \
    -d '{
    "tags": [
        {
            "id": "500fedd3-2140-4225-87d4-a22484222776"   -- required, tag identifier,
        }
    ]
  }'
Sample response 200 - OK - tags have been assigned successfully
Note! Each time you assign new tags you overwrite the previous ones. This means if you want to remove tags from offers without assigning any new ones, you need to call up the resource and transfer an empty tags structure into it’s body.

	{
 		"tags":[]
 	}

Attachments

You can upload PDF attachments to your offers. We will present them under the offer description in the Additional information section. You can upload up to 9 attachments – one per each section:

  • Guide (MANUAL)

  • Special offer terms (SPECIAL_OFFER_RULES)

  • Competition terms (COMPETITION_RULES)

  • Book excerpt (BOOK_EXCERPT)

  • Manual (USER_MANUAL)

  • Installation manual (INSTALLATION_INSTRUCTIONS)

  • Game manual (GAME_INSTRUCTIONS)

  • Energy label (ENERGY_LABEL)

  • Product information sheet (PRODUCT_INFORMATION_SHEET)

Uploading attachments to offers:

  1. Create an attachment object to receive an attachment ID and URL to send the attachment to,
  2. Use the URL to submit the PDF file you want to upload,
  3. Add the attachment to the offer.

Create the attachment object

To add the attachment you must first create the attachment object via POST /sale/offer-attachments. Once you create the object, you will have:

  • attachment ID,

  • URL to upload the file to our server.

Sample request:

  curl -X POST \
    https://api.allegro.pl/sale/offer-attachments \
    -H 'Accept: application/vnd.allegro.public.v1+json' \
    -H 'Content-Type: application/vnd.allegro.public.v1+json' \
    -H 'Authorization: Bearer {token}'
    -d '{
    "type": "SPECIAL_OFFER_RULES",                              -- required, attachment type,
                                                                   supported values MANUAL,
                                                                   SPECIAL_OFFER_RULES,
                                                                   COMPETITION_RULES,
                                                                   BOOK_EXCERPT, USER_MANUAL,
                                                                   INSTALLATION_INSTRUCTIONS,
                                                                   GAME_INSTRUCTIONS, 
                                                                   ENERGY_LABEL,
                                                                   PRODUCT_INFORMATION_SHEET
    "file": {
        "name": "abcde.pdf"                                     -- required, name of the file you
                                                                   want to upload,
    }
  }'

Note! You can find the URL address to upload the file to our server in the response header. The URL is unique and one-time. As its format may change over time, you should always use the address from the header. Do not create the address from available elements.

Sample response 201 - created - attachment object has been created successfully
Response header:

	Location: http://upload.allegro.pl/sale/offer-attachments/e9d1bf7c-804e-4faf-9e24-b2d3aa3eda05

Response body:

  {
    "id": "e9d1bf7c-804e-4faf-9e24-b2d3aa3eda05",              -- ID of the attachment draft,
    "type": "SPECIAL_OFFER_RULES",                             -- attachment type,
    "file": {
        "name": "abcde.pdf"                                    -- name of the file you upload,
    }
  }

Uploading PDF files

Now you can upload the attachment to our server. Use the address you received in the header of the response (in the Location field) to the previous call.

Sample request:

  curl -X PUT \
  http://upload.allegro.pl/sale/offer-attachments/{attachmentId} \
    -H 'Accept: application/vnd.allegro.public.v1+json' \
    -H 'Content-Type: application/pdf' \
    -H 'Authorization: Bearer {token}
    --data-binary "@abcde.pdf"                             -- required, content of the file
                                                           with the attachment in a
                                                           biinary form

Sample response:
  {
    "id": "07ee5e36-afc7-41eb-af49-3df5354ef858",          -- ID of the attachment draft,
    "type": "SPECIAL_OFFER_RULES",                         -- rattachment type,
    "file": {
        "name": "abcde.pdf",                               -- name of the file you upload,
        "url": {adres_pliku}                               -- address under which the attachment
                                                           is available.
    }
  }

Adding an attachment to the offer

Use PUT /sale/offers/{offerId} to add the attachment to the offer – provide its ID in the attachments structure.

	"attachments": [
            {
                "id": "07ee5e36-afc7-41eb-af49-3df5354ef858"
            }
        ]

Size tables

Retrieve it via:

Provide size table identifier in the sizeTable.id field to assign size table to an offer.

More information about Size tables you will find in our news.

12. Complete offer data

Once you received the offer ID in the id field in the response to POST /sale/offers, use via PUT /sale/offers/{offerId} to complete the data in the offer draft. If you transfer incomplete data, we will return logic errors that block the listing process, e.g. offer description is required.

Note! If you want to update an ongoing offer:

  • retrieve its data via GET /sale/offers/{offerId}. Next, when you update the offer using PUT /sale/ offers/{offerId}, transfer the same structure you received earlier in the response. Even if you update only one field, you have to send the complete structure of the offer fields;
  • use PATCH /sale/product-offers/{offerId} and in the structure provide only the field that you want to update. You can find more information about the PATCH method in our guide.

Use PUT /sale/offers/{offerId} to complete data in the draft offer. Below we described fields you have to transfer to publish the offer on the site.

Note! Remember to send information about handlingTime with shippingRates ID and sellingMode format.

Click to view sample request:
curl -X PUT 
'https://api.allegro.pl/sale/offers/{offerId} -H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.public.v1+json'
-H 'Content-Type: application/vnd.allegro.public.v1+json'
-d '{ "id": "7276261934", – offer ID "name": "Oferta testowa", – required, title of a retrieved offer "product": { "id": "634238b1-4385-4de7-9c00-dfa49fce16ab" – product ID "category": { "id": "257150" – required, category of the lowest tier that hosts the offer. Use GET /sale/categories?parent.id={catId} to retrieve category IDs. }, "parameters": [ – required, offer parameters, to check parameters supported in a particular category use GET /sale/categories/{categoryId}/parameters { "id": "11323", "valuesIds": [ "11323_1" ], "values": [], "rangeValue": null }, { "id": "128188", "valuesIds": [ "128188_1" ], "values": [], "rangeValue": null }, { "id": "127448", "valuesIds": [ "127448_1" ], "values": [], "rangeValue": null }, { "id": "4386", "valuesIds": [ "4386_1" ], "values": [], "rangeValue": null }, { "id": "219", "valuesIds": [ "219_2", "219_256", "219_4" ], "values": [], "rangeValue": null }, { "id": "225693", – GTIN parameter "valuesIds": [], (info: http://developer.allegro.pl/en/news/#gtin) "values": [ "6901443187416" ], "rangeValue": null } ], "description": { – required, offer content "sections": [ { "items": [ { "type": "TEXT", "content": "<p>Tekstowy opis przedmiotu</p>" }, { "type": "IMAGE", "url": "https://e.allegroimg.com/original/01fd60/4ea8d18e4275b0878b7f0562067e&#34; } ] }, { "items": [ { "type": "TEXT", "content": ""<p>Tekstowy opis przedmiotu</p>"" } ] } ] }, "images": [ – required image paths; send photos via POST /sale/images. The first photo in the array is also the first offer photo (thumbnail). { "url": "https://e.allegroimg.com/original/01fd60/4ea8d18e4275b0878b7f0562067e&#34; }, { "url": "https://e.allegroimg.com/original/018474/c62b54a74120a7983b09d0fa4a4e&#34; }, { "url": "https://8.allegroimg.com/original/013a51/4dd0904a4169ad8b0d25a8984b48&#34; }, { "url": "https://2.allegroimg.com/original/01b48e/6e777def4a71ba68952358bd2072&#34; } ], "compatibilityList": { – compatibility list, "id": "d04e8a0c-40a1-4c53-8902-ffee7261845e-922db1ed6fa1c9731d50ce251007ab400247b0ebb62f1006493f5b6c418bb0fa-2", "type": "PRODUCT_BASED" }, "tecdocSpecification": { – TecDoc specification for automotive parts "id": "e3725f4b-1b4b-4e39-ad7f-331a2c858a7f" }, "sellingMode": { – required, sales format, three values are supported: BUY_NOW (Buy it Now); AUCTION (auction); ADVERTISEMENT (classified ad) "format": "BUY_NOW", "price": { "amount": "1499", – required, offer price in the case of BUY_NOW (Buy it Now) and ADVERTISEMENT (classified ad) formats "currency": "PLN" }, "netPrice": null, – net price, calculated automatically based on the VAT rate
"startingPrice": null, – starting price, available in AUCTION (auction) "minimalPrice": null – reserve price, available in AUCTION (auction) }, "tax": { – VAT rate "id": "f40ae51c-70a2-4882-98a7-6272404f0ec5"
}, "stock": { "available": 4, – required, number of available items NOTE! Do not fill it out for offers of ADVERTISEMENT (classified ad) type; however for AUCTION (auction) offers provide 1 "unit": "UNIT" required, three values are supported: UNIT (pieces); SET (sets); PAIR (pairs). NOTE! Do not fill it out for offers of ADVERTISEMENT (classified ad) }, "publication": { "republish": true, – not required, automatically republish offers. Note! You can automatically republish offers or auctions: - offers are republished with initial stock, regardless of how many items you have sold. - auctions are republished only if they were not concluded with purchase. "duration": null, – required, offer duration, supported values: null (until all items are sold out), P3D (3 days); P5D (5 days); P7D (7 days); P10D (10 days); P20D (20 days); you can also provide the time in hours, e.g.: P72H (3 days). You cannot provide null in offers of AUCTION (auction) type and the allowed values are: P1D (1 day); P3D (3 days); P5D (5 days); P7D (7 days); P10D (10 days); However, the offers of ADVERTISEMENT (classified ad) type support the following values: null (for an indefinite time – fees are charged every 10 days); P10D (10 days); P20D (20 days); P30D (30 days) "status": "INACTIVE", – offer status, three values are supported: ACTIVE (active on the site), INACTIVE (inactive), ENDED (ended on the site) "startingAt": null, – not required, offer start time, applies to scheduled offers "endingAt": null, – not required, offer end time "endedBy": null – not required, reason of ended, four values are supported: USER (ended by user), ADMIN (ended by admin), EXPIRATION (available items had sold out or offer duration had expired), ERROR (internal problem) }, "delivery": { "shippingRates": { "id": "4b9ad5b9-7ee9-409b-86f5-578672c13df8" – required, shipping price list ID number, retrieve via GET /sale/shipping-rates. In the case of offers of ADVERTISEMENT (classified ad) type leave this field empty by transferring “delivery”: null }, "handlingTime": "PT168H", – required, shipping time; supported values: PT0S (immediately), PT24H (24 hours), P2D (2 days), P3D (3 days), P4D (4 days), P5D (5 days), P7D (7 days), P10D (10 days), P14D (14 days), P21D (21 days), duration can be also provided in hours, e.g. PT72H (3 days). It is not required for offers of ADVERTISEMENT (classified ad) type. "additionalInfo": "Additional delivery information" – not required, additional information on delivery; you can provide here information in a text form to be displayed in the “Delivery and payment” section. "shipmentDate":"2018-04-01T08:00:00Z" – shipping from - e.g. for pre-sale. Record of date consistent with ISO8601. }, "payments": { "invoice": "VAT" – required, information about an invoice; four values are supported: VAT (VAT invoice); VAT_MARGIN (VAT invoice margin); WITHOUT_VAT (invoice without VAT); NO_INVOICE (I don't issue invoices) }, "discounts": { – not required, information about discounts, "wholesalePriceList": { retrieve a wholesale price list identifier "id": "5637592a-0a24-4771-b527-d89b2767d821" via GET /sale/loyalty/promotions } and filter “promotionType=WHOLESALE_PRICE_LIST” }, "afterSalesServices": { – offer terms; required in the case of company accounts. In the case of offers of ADVERTISEMENT (classified ad) type this feature is unavailable; transfer "afterSalesServices": null "impliedWarranty": { "id": "b0590fac-9858-4d01-8487-1c6a09c55a68" – required in the case of company accounts, information on complaints; retrieve a particular identifier via GET /after-sales-service-conditions/implied-warranties }, "returnPolicy": { "id": "c27c2ddd-f587-44db-b3c8-1f181964ea4d" – required in the case of company accounts; return policy; retrieve identifiers via GET /after-sales-service-conditions/return-policies }, "warranty": { "id": "f8694df6-f020-4a27-ac0a-f4f959969e14" – not required, information on warranties; retrieve the identifiers via GET via /after-sales-service-conditions/warranties } }, "additionalServices": null, – additional services; retrieve identifiers of your groups of additional services via GET /sale/offer-additional-services/groups. The feature is not available to offers of ADVERTISEMENT (classified ad) type.; transfer "additionalServices": null. "sizeTable": null, – size table ID, retrieve identifiers via GET /sale/size-tables "fundraisingCampaign": null, – not required, charity organization ID, retrieve identifiers via GET /charity/fundraising-campaigns "promotion": { – not required, promo options; select one value next to each option: false (inactive); true (active) "emphasized": true, – emphasized "bold": false, – bold "highlight": false, – highlight "departmentPage": false, – offer promoted on a category page "emphasizedHighlightBoldPackage": false – promo package: emphasized, highlighting and bold }, "location": { – required, for offer with a delivery method it is a parcel dispatch location. For offers with personal pick-up it is a pick-up location, additionally we recommend to use points of service (https://developer.allegro.pl/documentation/#tag/Points-of-service) Before completing this field, you must first assign a shippingRate and set a sellingMode "countryCode": "PL", – required, country code according to ISO 3166-1 alpha-2 "province": "WIELKOPOLSKIE", – required in the case of countryCode “PL”, province, available 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 for addresses in Poland, postal code }, "external": { – not required, external ID / signature assigned "id":"4131asdsad40011" by the seller, e.g. to link an offer }, with a product in the seller's warehouse. You can provide here a default string of characters that will be displayed after offer relisting. "attachments": [ { "id": "07ee5e36-afc7-41eb-af49-3df5354ef858" – not required, attachments ID } ] "contact": null, – not required, identifier of contact data for sales format ADVERTISEMENT (classified ad); retrieve it via GET /sale/offer-contacts "validation": { "errors": [], – information on potential errors; we will inform you if you provide e.g. incorrect price list ID. "validatedAt": "2018-04-06T08:29:37.461Z" – date of last offer validation }, "createdAt": "2018-04-06T08:26:32Z", – required, offer creation date "updatedAt": "2018-04-06T08:29:38.664Z" – required, last offer update }'

Click to view sample response:
{
    "id": "7276377308",
    "name": "Oferta testowa",
    "category": {
        "id": "257150"
    },
    "parameters": [
        {
            "id": "11323",
            "valuesIds": [
                "11323_1"
            ],
            "values": [],
            "rangeValue": null
        },
        {
            "id": "128188",
            "valuesIds": [
                "128188_1"
            ],
            "values": [],
            "rangeValue": null
        },
        {
            "id": "127448",
            "valuesIds": [
                "127448_1"
            ],
            "values": [],
            "rangeValue": null
        },
        {
            "id": "4386",
            "valuesIds": [
                "4386_1"
            ],
            "values": [],
            "rangeValue": null
        },
        {
            "id": "219",
            "valuesIds": [
                "219_2",
                "219_256",
                "219_4"
            ],
            "values": [],
            "rangeValue": null
        },
        {
            "id": "225693",
            "valuesIds": [],
            "values": [
                "6901443187416"
            ],
            "rangeValue": null
        }
    ],
    "description": {
        "sections": [
            {
                "items": [
                    {
                        "type": "TEXT",
                        "content": "<p>Tekstowy opis przedmiotu</p>"
                    },
                    {
                        "type": "IMAGE",
                        "url": "https://e.allegroimg.com/original/01fd60/4ea8d18e4275b0878b7f0562067e&#34;
                    }
                ]
            },
            {
                "items": [
                    {
                        "type": "TEXT",
                        "content": "<p>Tekstowy opis przedmiotu</p>"
                    }
                ]
            }
        ]
    },
    "images": [
        {
            "url": "https://e.allegroimg.com/original/01fd60/4ea8d18e4275b0878b7f0562067e&#34;
        },
        {
            "url": "https://e.allegroimg.com/original/018474/c62b54a74120a7983b09d0fa4a4e&#34;
        },
        {
            "url": "https://8.allegroimg.com/original/013a51/4dd0904a4169ad8b0d25a8984b48&#34;
        },
        {
            "url": "https://2.allegroimg.com/original/01b48e/6e777def4a71ba68952358bd2072&#34;
        }
    ],
    "compatibilityList": {
        "id": "d04e8a0c-40a1-4c53-8902-ffee7261845e-922db1ed6fa1c9731d50ce251007ab400247b0ebb62f1006493f5b6c418bb0fa-2",
        "type": "PRODUCTBASED",
        "items": [
            {
                "text": "ALFA ROMEO 147 (937) 1.6 16V T.SPARK (937.AXA1A, 937.AXB1A, 937.BXB1A) (AR 32104) 1598ccm 120KM/88kW 200101-201003, szczegóły: Strona zabudowy: z lewej, z prawej, Oś tylna, System hamulcowy: LUCAS, dla numeru artykułu: 343599, 343598"
            },
        …
            {
                "text": "SKODA RAPID Spaceback (NH1) 1.2 TSI (CBZB) 1197ccm 105KM/77kW 201207-, szczegóły: Strona zabudowy: z prawej, Oś tylna, z lewej, System hamulcowy: LUCAS, dla numeru artykułu: 342966, 342967, dla numeru PR: 1KT"
            }
        ]
    },
    "tecdocSpecification": {
        "id": "e3725f4b-1b4b-4e39-ad7f-331a2c858a7f",
        "items": [
            {
                "name": "Wysokość [mm]",
                "values": [
                    "51"
                ]
            },
            {
                "name": "Materiał",
                "values": [
                    "stal"
                ]
            },
            {
                "name": "średnica [mm]",
                "values": [
                    "38"
                ]
            },
            {
                "name": "Wersja TecDoc",
                "values": [
                    "TecDoc 0619"
                ]
            }
        ]
    },
    "sellingMode": {
        "format": "BUY_NOW",
        "price": {
            "amount": "1499",
            "currency": "PLN"
        },
        "netPrice": {
            "amount": "1218.70",
            "currency": "PLN"
        },
        "startingPrice": null,
        "minimalPrice": null
    },
    "tax": {
        "id": "f40ae51c-70a2-4882-98a7-6272404f0ec5",
        "rate": “23.00”,
        "subject": “GOODS”,
        "exemption": “MONEY_EQUIVALENT”
    },
    "stock": {
        "available": 4,
        "unit": "UNIT"
    },
    "publication": {
        "republish": true,
        "duration": null,
        "status": "INACTIVE",
        "startingAt": null,
        "endingAt": null
    },
    "delivery": {
        "shippingRates": {
            "id": "4b9ad5b9-7ee9-409b-86f5-578672c13df8"
        },
        "handlingTime": "PT168H",
        "additionalInfo": ""
        "shipmentDate":"2018-04-01T08:00:00Z"
    },
    "payments": {
        "invoice": "VAT"
    },
    "discounts": {
       "wholesalePriceList": {
           "id": "5637592a-0a24-4771-b527-d89b2767d821"
       }
    },
    "afterSalesServices": {
        "impliedWarranty": {
            "id": "b0590fac-9858-4d01-8487-1c6a09c55a68"
        },
        "returnPolicy": {
            "id": "c27c2ddd-f587-44db-b3c8-1f181964ea4d"
        },
        "warranty": {
            "id": "f8694df6-f020-4a27-ac0a-f4f959969e14"
        }
    },
    "additionalServices": null,
    "sizeTable": null,
    "fundraisingCampaign": null,
    "promotion": {
        "emphasized": true,
        "bold": false,
        "highlight": false,
        "departmentPage": false,
        "emphasizedHighlightBoldPackage": false
    },
    "location": {
        "countryCode": "PL",
        "province": "WIELKOPOLSKIE",
        "city": "Poznań",
        "postCode": "60-166"
    },
    "external": {                               – niewymagany, zewnętrzny ID / sygnatura,
        "id":"4131asdsad40011"                  który nadaje sprzedający, np. aby powiązać ofertę
                },                              z produktem w swoim magazynie. Możesz wprowadzić
                                                tutaj dowolny ciąg znaków - będzie on dostępny
                                                również po wznowieniu oferty.
    "attachments": [],
    "contact": null,
    "validation": {
        "errors": [],
        "validatedAt": "2018-04-06T09:34:40.142Z"
    },
    "createdAt": "2018-04-06T09:29:47Z",
    "updatedAt": "2018-04-06T09:34:40.142Z"
}

13. Offer publication

Once the offer is complete and properly validated, use PUT /sale/offer-publication-commands/{commandId} to publish the offer on the site. It is an asynchronous method - use GET /sale/offer-publication-commands/{commandId}/tasks to retrieve detailed report of your task. In commandId provide the value in the UUID (universally unique identifier) format. It is a globally unique identifier that consists of 32 hexadecimal numbers (e.g. 21ae4ed1-eab7-34ea-b605-cf2e22b5eed3). Remember to implement the mechanism for generating UUIDs in your software.


Note! Use this resource to:

  • end particular offers, by providing END in the action field,

  • schedule offers, by providing the listing date in the scheduleFor field,

  • relist a finished offer - (status ENDED) with ‘ACTIVATE’ value in action filed in PUT /sale/offer-publication-commands/{commandId}. Such an offer will be once again available in Allegro.


Sample request:

  curl -X PUT \
    'https://api.allegro.pl/sale/offer-publication-commands/{commandId}
    -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 (offer activation)
                                               and END (offer end)
        "scheduledFor":"2018-03-28T12:00:00.000Z"   -- not required, provide it, if you
                                               want to schedule the publication
                                               for a later date
    },
    "offerCriteria": [
        {
            "offers": [                     -- required; an array of objects with offer
											IDs, maximum of 1000 offers
                {
                    "id": "7276377308"
                }
            ],
            "type": "CONTAINS_OFFERS"       -- required, at present only one
                                               value is supported: CONTAINS_OFFERS
                                               (offers with status to be changed)
        }
    ]
  }
Sample response:
  {
    "id": "3380d97f-0d32-4747-8a17-1da38f9499de",
    "taskCount": {
        "total": 0,
        "success": 0,
        "failed": 0
    }
  }

Task list

Use GET /sale/offer-publication-commands/{commandId} to retrieve information about the offer listing statuses. You will receive a summary with a number of correctly listed offers 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 about publication

Use GET /sale/offer-publication-commands/{commandId}/tasks to retrieve information about the offer statuses on the site. The response will contain:

  • IDs of offers you wanted to list on the site,

  • offer editing status – whether it was successful,

  • date of offer editing order,

  • date of order execution – listing or ending an offer.

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' \

Sample response:
  [
    {
            "offer": {
                "id": "7168735300"
            },
            "message": "",                    -- explanation why it failed to list the offer
            "status": "SUCCESS",              -- offer listing status; three values are supported:
                                              SUCCESS (publication was successful,
                                              the offer should be active within 60 minutes);
                                              FAIL (errors have occurred and the offer
                                              is inactive); NEW (offer is being listed,
                                              the action is in progress)
            "scheduledAt": "2018-03-01T11:02:50.005+01:00",
            "finishedAt": "2018-03-01T11:02:51.691+01:00",
            "field": "publication"
      }
    ]

14. How to list a similar offer

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

  • offer ID,

  • last offer validation,

  • offer creation date,

  • last offer update,

  • “publication” section.

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

15. Questions and answers

1. How can I list an auction with the Buy it Now option?

To list such offers, transfer AUCTION in the “format” field and fill out:

  • startingPrice - starting price

  • minimalPrice - reserve price. This field is not required.

2. Why has the draft been introduced?

Drafts allows you to start working on an offer and finish it whenever it suits you, e.g. when you want to provide the final version of the content. However, you can complete the draft immediately, without saving it for later, and list the offer.

3. Why have you introduced a separate resource for images?

You can present high-resolution images within your offer. However, such files have a significant size. For this reason, we have introduced a separate resource for images in order to decrease the request size. As a result, offers are listed faster.

4. Why have you introduced a separate resource for shipping price lists?

As shipping price lists are not linked to an offer, with a separate resource bulk editing of shipping price lists is much faster. Just edit the price list, and the cost will be updated in all offers to which the price list is linked. Therefore, you can react immediately to any changes introduced by the courier companies.

5. How can I schedule an offer?

Set the listing date by calling PUT on /sale/offer-publication-commands/{commandId}. Just provide the listing date in the scheduledFor field.

6. I got a message - “You cannot create new drafts - your account has exceeded the maximum number {maxInactiveOffers} of drafts.” - What should I do?

You received this message because you exceeded the limit of drafts (offers with the status “INACTIVE”). To solve this problem:

7. I receive error 401 Unauthorized with a message “Empty user_name claim” when I try to create an offer draft. What does it mean?

You are using token from client_credentials type of authorization with no user context. To create an offer draft you should use token generated via code or device flow.

8. I receive error 422 when I try to create an offer draft. What does it mean?

Make sure the structure of your request is valid and you properly provide all of the values. You can find a sample request in our guide.

9. When I try to activate offers via PUT /sale/offer-publication-commands/{commandId} I receive zeros in the response. Is this the proper behavior?

Yes, this is because this resource is running asynchronously. Use GET /sale/offer-publication-commands/{commandId}/tasks to check detailed task status.

10. I am providing the completed location field in my request, but in the response I receive null. What am I doing incorrectly?

Make sure that in addition to the correctly completed location field, you also provide values for delivery.shippingRates and sellingMode.

10. I receive error 422 in the response with a message “Description images are not valid”. What does it mean?

Make sure that the image links that you pass in the description section are also provided in the images section.

16. List of resources

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

List of basic resources used in tutorial:

List of supporting resources used in tutorial: