1. Why assigning offers to a products is important

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.

If you do not assign offers to products, we will display the offers on the bottom of a list of products in the category. Therefore, we highly recommend assigning offers to products. As a result, your offer will be grouped and included on the list of offers presenting the product. It is the best way to reach customers.

Visit page for sellers for more details.

2. How to search for products

Call GET /sale/products to search for products in Allegro database. The response will include a product ID and basic data about its category and parameters. An additional request limit is applied to this resource.

We work on improving our database by updating product data and adding new categories.

Categories where you can assign offer to a product

You can assign offers to products in selected categories. You will receive product data only in categories marked “productListingEnabled”: true after calling GET /sale/categories.


Sample request:

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


Sample response:

  {
    "categories": [
        {
            "id": "251462",
            "name": "Galaxy S6",
            "parent": {
                "id": "435"
            },
            "leaf": true,
            "options": {                        
                "offersWithProductPublicationEnabled": true,    -- if the category supports  
                                                                assigning offers to a product
                "productCreationEnabled": true,                 -- if the category supports adding a product
            ...
  ]}

How to find a product

EAN

Call GET /sale/products and provide EAN of the product you are looking for.


Sample request:

  curl -X GET \
  'https://api.allegro.pl/sale/products?ean=888462600712' \
  -H 'Authorization: Bearer {token}' \
  -H 'accept: application/vnd.allegro.public.v1+json'

Click to view sample response:
{
 "products": [
  {
   "id": "5272069b-0759-4283-8ba7-7f05b416f1d9",        -- product ID – use it in an offer to assign
                                                        the offer to a product
   "name": "Smartfon Apple iPhone 6S srebrny 128 GB",   -- product name
   "category": {
    "id": "253002"                                      -- product category
   },
   "parameters": [                                      -- product parameters
    {
     "id": "224017",                                    -- parameter ID
     "name": "Kod producenta",                          -- parameter name
     "valuesLabels": [                                  -- parameter value label
      "MKQU2PM/A"
     ],
     "values": [
      "MKQU2PM/A"                                       -- parameter value - for string type
     ],
     "unit": null,                                      -- unit for parameter value. If a value
                                                        is not  associated with any unit,
                                                        we return null
     "options": {
      "identifiesProduct": true                         -- this field will be used to
     }                                                  add products to a database,
    },                                                  i.e. in a process we are working on
    {
     "id": "127448",                                    -- parameter ID
     "name": "Kolor",                                   -- parameter name
     "valuesLabels": [                                  -- parameter value label
      "srebrny"
     ],
     "valuesIds": [                                     -- parameter value ID -
      "127448_8"                                        for dictionary type
     ],
     "unit": null,                                      -- unit for parameter value. If a value
                                                        is not  associated with any unit,
                                                        we return null
     "options": {
      "identifiesProduct": true
     }
    },
    {
     "id": "202733",                                    -- parameter ID
     "name": "Funkcje aparatu",                         -- parameter name
     "valuesLabels": [                                  -- parameter value label
      "HDR",
      "autofocus",
      "lampa błyskowa",
      "panorama",
      "samowyzwalacz",
      "wykrywanie twarzy",
      "zdjęcia seryjne"
     ],
     "valuesIds": [                                     -- parameter value ID -
      "202733_1024",                                    for multi-value type
      "202733_2",
      "202733_1",
      "202733_4",
      "202733_128",
      "202733_32",
      "202733_64"
     ],
     "unit": null,                                      -- unit for parameter value. If a value
                                                        is not  associated with any unit,
                                                        we return null
     "options": {
      "identifiesProduct": false
     }
    },
    {
    "id": "225693",                                     -- parameter ID
    "name": "EAN",                                      -- parameter name
    "valuesLabels": [
        "888462600712"                                  -- parameter value label
    ],
    "values": [
        "888462600712"                                  -- parameter value
    ],
    "unit": null,
    "options": {
        "identifiesProduct": true,
        "isGTIN": true                                  -- this field will be used when you
                                                        suggest a product, if it has many values,  
                                                        you can send in request only one value  
    }                                                   
    },
...
   ],
   "images": [                                          -- product photos
    {
     "url": "https://a.allegroimg.com/original/00e0c9/1d7c95614fd6a7c713b075d0251a/
     Smartfon-Apple-iPhone-6S-srebrny-128-GB"
    }   
   ]}]}

Phrase

Call GET /sale/products and provide product name as a search phrase parameter to find the product.

  GET https://api.allegro.pl/sale/products?phrase=Harry Potter i Książę Półkrwi


Category - in response in “categories” section you can find how many search results belong to given category. You can use an ID of given category to narrow the search results.

  GET https://api.allegro.pl/sale/products?phrase=Harry Potter i Książę Półkrwi&category.id=66781


Similar categories - some categories have sets of similar categories. To extend the product search with a set of similar categories, pass the value SIMILAR_CATEGORIES in the searchFeatures parameter. You can only use this parameter if you also pass the category.id parameter in the same request.

  GET https://api.allegro.pl/sale/products?phrase=memory card&category.id=16242&searchFeatures=SIMILAR_CATEGORIES

We will sum up the number of results from all categories for the category specified in the category.id parameter in the categories.subcategories.count field.

information If you expand your search to include a set of similar categories, you will not get filters in response. Therefore - cannot use the filtering options.


Paging - if search query returns more than 30 results, the response is divided into multiple pages. In the first response you can find next page ID, which can be used to get next search results.

  GET https://api.allegro.pl/sale/products?phrase=iphone%206s&category.id=253002&202869=214189


Filters - to narrow received search results when you search for a product in selected category, a list of filters is returned:

  • You will find the list in Filters section.

  • Filters are returned for selected category. You will receive more filters in lowest levels of the category tree.

  • Filters works only for categories they were returned in.

  • You may use many filters in a search query, we recognize them as connected with AND operator. In response you will receive products, which meets every condition given in the query.

  • Incorrect filters are ignored - you will receive search results as if the incorrect filter was not used.

  • In the dictionary filter types you find “count” - the number of products with given parameter values:

    • For filters used in query - “count” remains unchanged - in response you get the number of products for each filter value as if the filter was not used.

    • For filters not used in query - “count” is recalculated - in response you get the number of products for each filter value, which is sum of products that meet the current search conditions and those that meet the search conditions with a certain value.


Examples of filters:

  • SINGLE - filter for single selection parameter
    MULTI - filter for multiselect parameter
    You can create the filter by using filter id and value id according to formula: {filter.id}={filter.value}.

For example, you want to narrow the search results for “iphone 6s” phrase to models with 128 GB (filter.value=214189) of memory (filter.id=202869):

  GET https://api.allegro.pl/sale/products?phrase=iphone%206s&category.id=253002&202869=214189

You may use many values for selected filter in a search query, we recognize them as connected with OR operator. In response you will receive products, which meets at least one condition given in the query.

  • NUMERIC - filter for number parameters
    You can create the filter by using filter id and range of values with form and to suffixes according to formula: {filter.id}.from={value}&{filter.id}.to={value}.

For example you want to narrow the search results for “Harry Potter” phrase to books released between 2017 and 2019 (filter.id=74):

  GET https://api.allegro.pl/sale/products?phrase=Harry%20Potter&category.id=66781&
  74.from=2017&74.to=2019

Do not use many ranges for certain filter.id, because no results will be returned.

  • NUMERIC_SINGLE - filter for range parameters
    You can create the filter by using filter id and value according to formula: {filter.id}={value}.

For example you want to narrow the search results for “Lawn mower” phrase to models with a cutting height (filter.id = 1117823) equal to 5 cm:

  GET https://api.allegro.pl/sale/products?phrase=Kosiarka%20spalinowa&category.id=85213&1117823=5

Do not use many values for certain filter.id, because no results will be returned.


Sample request:

  curl -X GET \
  'https://api.allegro.pl/sale/products?phrase=Harry%20Potter&category.id=66781' \
  -H 'Authorization: Bearer {token}' \
  -H 'accept: application/vnd.allegro.public.v1+json'


Click to view sample response:
{
 "products": [                                      – list of products that meet search criteria
  {
"id": "05662917-d96a-47c3-ac36-26a178f0395f", – product ID – use it in an offer to assign a offer to a product "name": "Harry Potter i więzień Azkabanu – product name ilustrowany J. K. Rowling", "category": { "id": "91436" – product category }, "parameters": [ – product parameters { "id": "223545", – parameter ID "name": "Tytuł", – parameter name "valuesLabels": [ – parameter value label "Harry Potter i więzień Azkabanu ilustrowany" ], "values": [ – parameter value "Harry Potter i więzień Azkabanu ilustrowany" ], "unit": null, – unit for parameter value. If a value is not associated with any unit, we return null "options": { "identifiesProduct": true – this field will be used to } add products to a database, }, i.e. in a process we are working on … ], "images": [ – product photos { "url": "https://0.allegroimg.com/original/ 0030ae/89c1446a4cadab5b4e144092be30/ Harry-Potter-i-wiezien-Azkabanu-ilustrowany-J-K-Rowling" } ] }, { "id": "2d91816e-2b18-46e0-85f6-8f54838db73c", – another product "name": "Harry Potter i Zakon Feniksa that meets search criteria J. K. Rowling", … } ] } ], "categories": { "subcategories": [ – list of subcategories of category used in request { If category.id is not provided, "id": "66784", list of main categories is returned "name": "Bajki i wierszyki", "count": 1 }, { "id": "66791", – category ID - you can use it to narrow the search resulst "name": "Literatura dziecięca", – category name "count": 54 – number of products in given category, }, that meet search criteria { "id": "260531", "name": "Bohaterowie telewizyjni", "count": 0 },

…. ], "path": [ – search path - provides details for
{ which category and on which level of "id": "954b95b6-43cf-4104-8354-dea4d9b10ddf", category tree the search was performed "name": "Allegro" }, { "id": "38d588fd-7e9c-4c42-a4ae-6831775eca45", "name": "Kultura i rozrywka" }, { "id": "7", "name": "Książki i Komiksy" }, { "id": "66781", "name": "Książki dla dzieci" } ] }, "filters": [ – list of filters which can be used { to narrow the search results "id": "7773", "name": "Okładka", "type": "SINGLE", "values": [ { "name": "miękka", "value": "1", "idSuffix": null, "count": 35, "selected": false }, … { "name": "zintegrowana", "value": "5", "idSuffix": null, "count": 0, "selected": false } ], "minValue": null, "maxValue": null, "unit": null }, { "id": "74", "name": "Rok wydania", "type": "NUMERIC", "values": [ { "name": "from", "value": null, "idSuffix": ".from", "count": null, "selected": false }, { "name": "to", "value": null, "idSuffix": ".to", "count": null, "selected": false } ], "minValue": 1400, "maxValue": 2099, "unit": null }], "nextPage": { – ID of the next page of search results "id":
"AoIIRL1bQT8FNDRhOWVjNTktOWEyYy00YjMxLWE4N2YtYjFmZTRhOThkY2Q3" }}

3. How to get the complete data on a product

Call GET /sale/products/{productId} to retrieve detailed information concerning the product. The response will include a product ID and complete data about category and parameters you will provide in the offer. An additional request limit is applied to this resource.


Sample request:

  curl -X GET \
  https://api.allegro.pl/sale/products/634238b1-4385-4de7-9c00-dfa49fce16ab \
  -H 'Authorization: Bearer {token}' \
  -H 'accept: application/vnd.allegro.public.v1+json'
Click to view sample response:
 {
 "id": "634238b1-4385-4de7-9c00-dfa49fce16ab",      -- product ID; use in the offer
                                                    to assign it to a product
 "name": "Harry Potter i Książę Półkrwi",           -- product name
 "category": {
  "id": "91447",                                     -- product category
  "similar": [                                       -- similar categories list
         {
        "id": "12345"                                -- id of similar category
        }
    ]
  },
  "parameters": [                                   -- product parameters
   {
  "id": "245669",                                   -- GTIN parameter
  "name": "ISBN",
  "valuesLabels": [
      "9788380082434"
  ],
  "values": [
      "9788380082434"
              ],
  "unit": null,
  "options": {
      "identifiesProduct": true,
      "isGTIN": true
   }
  },
  {
   "id": "7773",
   "name": "Okładka",
   "valuesLabels": [
    "twarda"
   ],
   "valuesIds": [
    "7773_3"
   ],
   "unit": null,                                    -- unit for parameter value. If a value
                                                    is not  associated with any unit,
                                                    we return null
   "options": {
    "identifiesProduct": true
   }
  },
...
 ],
 "images": [                                        -- product photos
  {
   "url": "https://e.allegroimg.com/original/05239b/a708a8864b2bb2c9b23e450bd98e/
   Harry-Potter-i-Ksiaze-Polkrwi-J-K-Rowling-a708a8864b2bb2c9b23e450bd98e"
  },
  {
   "url": "https://5.allegroimg.com/original/00cc55/670c94c04db19158b020d827c715/
   Harry-Potter-i-Ksiaze-Polkrwi-J-K-Rowling"
  }
 ],    
 "offerRequirements": {                             -- conditions which an offer must meet
  "parameters": [                                   to be assigned with the product,
   {                                                i.e. Condition parameter must be set to New.
    "id": "11323",
    "name": "Stan",
    "valuesLabels": [
     "Nowy"
    ],
    "valuesIds": [
     "11323_1"
    ],
    "options": {
     "identifiesProduct": false
    }
   }
  ]
 },
 "compatibilityList": {
  "id": "d04e8a0c-40a1-4c53-8902-ffee7261845e-cf5b236d0f72d0abc0418669fe6569d73432b49250032a21f044696eed7e7d70-2",
                                                    -- compatibility list id
  "type": "PRODUCT_BASED",                          -- compatibility list type
  "items": [                                        -- text representation of the content of compatibility list
   {
    "text": "ALFA ROMEO 147 (937_) 1.6 16V T.SPARK (937.AXA1A, 937.AXB1A, 937.BXB1A) 2001/01-2010/03120KM/88kW"
   },
 ...   
   {
    "text": "SKODA RAPID Spaceback (NH1) 1.2 TSI 2012/07-105KM/77kW"
   }
  ]
 },
 "tecdocSpecification": {
  "id": "e3725f4b-1b4b-4e39-ad7f-331a2c858a7f",     -- TecDoc specification id
  "items": [                                        -- text representation of the content  
   {                                                of TecDoc specification
    "name": "Wysokość [mm]",
    "values": [
     "51"
    ]
   },
 ...   
   {
    "name": "Wersja TecDoc",
    "values": [
     "TecDoc 0619"
    ]
    }
   ]
  }
 }


If we have returned a set of similar categories in the category.similar list - it means that you can also assign this product with an offer in one of these similar categories.

Use GET ​/sale​/products​/{productId}?category.id={similarCategoryId} and in the category.id parameter put the id from the set of similar categories returned by us to filter the parameters for the selected similar category. In response, you will receive product parameters that you can use when listing an offer in a similar category.


Sample request:

  curl -X GET \
  ‘https://api.allegro.pl/sale/products/b2b61e23-b580-4471-b653-6ed25fd179f7?category.id=261573’ \
  -H 'Authorization: Bearer {token}' \
  -H 'accept: application/vnd.allegro.public.v1+json'
Click to view sample response:
{
   "id": "b2b61e23-b580-4471-b653-6ed25fd179f7",
   "name": "BIO pochodnia",
   "category": {
       "id": "261573",
       "similar": [
           {
               "id": "110914"
           },
           {
               "id": "305121"
           }
       ]
   },
   "parameters": [
       {
           "id": "237190",
           "name": "Marka",
           "valuesLabels": [
               "Marka"
           ],
           "values": [
               "Marka"
           ],
           "unit": null,
           "options": {
               "identifiesProduct": true
           }
       },
       {
           "id": "24231",
           "name": "Długość/wysokość",
           "valuesLabels": [
               "111 cm"
           ],
           "values": [
               "111"
           ],
           "unit": "cm",
           "options": {
               "identifiesProduct": true
           }
       },
       {
           "id": "219809",
           "name": "Kod produktu",
           "valuesLabels": [
               "test1"
           ],
           "values": [
               "test1"
           ],
           "unit": null,
           "options": {
               "identifiesProduct": true
           }
       },
       {
           "id": "225693",
           "name": "EAN",
           "valuesLabels": [
               "0000000909099"
           ],
           "values": [
               "0000000909099"
           ],
           "unit": null,
           "options": {
               "identifiesProduct": false,
               "isGTIN": true
           }
       }
   ],
   "images": [
       {
           "url": "https://c.allegroimg.com/original/0587c4/1a7a1b46438da3de2cf8a328791a"
       }
   ],
   "offerRequirements": {
       "parameters": []
   },
   "compatibilityList": null,
   "tecdocSpecification": null
}

4. How to manage products in offers

When you find the product, retrieve complete set of its data by calling GET /sale/products/{productId}. The response will include data on product category and parameters. Provide the data in requests concerning offer creating or editing.

If you want a full set of product data for one of the similar categories, use GET ​/sale​/products​/{productId}?category.id={similarCategoryId} and enter the identifier of the similar category in the category.id parameter.

Note! If the product includes several GTIN parameter values (EAN, ISBN or ISSN) remember that you can provide only one in the offer.

Listing a new offer assigned to a product

  1. Create a draft offer by providing:

    • offer title

    • product ID (product.id)

    • category ID or similar category ID matching selected product

    • parameters and parameters values matching selected product (in case when product has several EANs assigned, provide only one of them)

    • GTIN parameter matching selected product

    • content of compatibility list matching selected product

    • content of Tecdoc specification matching selected product.

  2. Provide other parameters and data necessary for listing the offer. Follow Listing offers guide.


Sample request to create draft offer assigned to a product

  curl -X POST \
  https://api.allegro.pl/sale/offers \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/vnd.allegro.public.v1+json' \
  -d '{
 "product": {
    "id": "634238b1-4385-4de7-9c00-dfa49fce16ab"        -- product ID {product.id}
 },
 "name": "Harry Potter i Książę Półkrwi J.K. Rowling",  -- offer title, can be different than product name
 "category": {                                          -- category ID matching selected product
  "id": "91447"
 },
 "parameters": [                                        -- parameters and parameters values
  {                                                     matching selected product
   "id": "11323",
   "name": "Stan",
   "valuesLabels": [
    "Nowy"
   ],
   "valuesIds": [
    "11323_1"
   ],
   "options": {
    "identifiesProduct": false
   }
  },
  {
   "id": "245669",                                     -- GTIN parameter
   "name": "ISBN",
   "valuesLabels": [
       "9788380082434"
   ],
   "values": [
       "9788380082434"
               ],
   "unit": null,
   "options": {
       "identifiesProduct": true,
       "isGTIN": true
    }
  },
  {
   "id": "7773",
   "name": "Okładka",
   "valuesLabels": [
    "twarda"
   ],
   "valuesIds": [
    "7773_3"
   ],
   "options": {
    "identifiesProduct": false
   }
  },
  {
   "id": "74",
   "name": "Rok wydania",
   "valuesLabels": [
    "2016"
   ],
   "values": [
    "2016"
   ],
   "options": {
    "identifiesProduct": false
   }
  },
  {
   "id": "223493",
   "name": "Liczba stron",
   "valuesLabels": [
    "704"
   ],
   "values": [
    "704"
   ],
   "options": {
    "identifiesProduct": false
   }
  },
  {
   "id": "223489",
   "name": "Autor",
   "valuesLabels": [
    "J.K. Rowling"
   ],
   "values": [
    "J.K. Rowling"
   ],
   "options": {
    "identifiesProduct": false
   }
  },
  {
   "id": "223541",
   "name": "Wydawnictwo",
   "valuesLabels": [
    "Media Rodzina"
   ],
   "valuesIds": [
    "223541_303353"
   ],
   "options": {
    "identifiesProduct": false
   }
  },
  {
   "id": "223545",
   "name": "Tytuł",
   "valuesLabels": [
    "Harry Potter i Książę Półkrwi"
   ],
   "values": [
    "Harry Potter i Książę Półkrwi"
   ],
   "options": {
    "identifiesProduct": false
   }
  }
 ],
 "compatibilityList": {
  "id": "d04e8a0c-40a1-4c53-8902-ffee7261845e-cf5b236d0f72d0abc0418669fe6569d73432b49250032a21f044696eed7e7d70-2",
                                                     -- compatibility list id matching selected    product
   "type": "PRODUCT_BASED"                           -- compatibility list type
   },
  "tecdocSpecification": {                           -- Tecdoc specification id
   "id": "e3725f4b-1b4b-4e39-ad7f-331a2c858a7f       matching selected product
  }
 }'

Assigning products to listed offers

You can assign products to offers with any status, i.e.: Draft, Active and Ended.

Call PUT /sale/offers/{offerId} and provide:

  • product ID (product.id)

  • category ID or similar category ID matching selected product

  • parameters and parameters values matching selected product (in case when product has several EANs assigned, provide only one of them)

  • GTIN parameter matching selected product

  • content of compatibility list matching selected product

  • content of Tecdoc specification matching selected product.

*Note! You can change the category up to 12 hours after first listing of the offer. It means that after 12 hours you will not be able to assign a product from category other than the one you selected to list your offer. In this case you can list a new offer with such product.

Updating information about a product in the offer

Products are similar to categories and parameters in terms of how they work. We work on improving our product database, by filling in missing parameters or updating them. For this reason, when you introduce changes in the offer, check product data. If the data is updated, you need to update product data in the offer.

You can update product data in offers of any status, i.e.: Draft, Active and Ended.

Call PUT /sale/offers/{offerId} and provide:

  • product ID (product.id)

  • category ID or similar category ID matching selected product

  • parameters and parameters values matching selected product (in case when product has several EANs assigned, provide only one of them)

  • GTIN parameter matching selected product

  • content of compatibility list matching selected product

  • content of Tecdoc specification matching selected product.

Note! You can change the category up to 12 hours after first listing of the offer. It means that after 12 hours you will not be able to assign a product from category other than the one you selected to list your offer. In this case you can list a new offer with such product.

Removing products from offers

Note! If you remove a product from the offer, we will not be able to group the offer with the product and the buyer will not reach it directly from the list of products. Visit page for sellers for more details.

Call PUT /sale/offers/{offerId} and give “null” in product.id (product ID)

5. How to check the process on the test environment

Allegro Sandbox mirrors features of the live environment. To use the test environment, use the appropriate addresses:

Production Sandbox
Resource address https://api.allegro.pl/ https://api.allegro.pl.allegrosandbox.pl/
Application registration https://apps.developer.allegro.pl/ https://apps.developer.allegro.pl.allegrosandbox.pl/
Authorization address https://allegro.pl/auth/oauth/ https://allegro.pl.allegrosandbox.pl/auth/oauth/


To test the entire process of linking an offer to a product, create your product using POST /sale/product-proposals or when you post a new offer via our website. The product will be available in the search engine GET /sale/products a few minutes after creation.

6. How to create a product

Verify if you can add a product to the given category

Call GET /sale/categories/{categoryId}. If in the response you will find “productCreationEnabled”=true, it means you can add products.

Remember that you can add products to the lowest-tier category marked “leaf”: true.

Retrieve parameters describing the product

When you establish the category for your product, call GET /sale/categories/{categoryId}/parameters to retrieve suitable parameters. The value true in the field:

  • options.describesProduct - means this is a product parameter and you can use it,

  • requiredForProduct - means the values for this parameter is required to create a product proposal.


Sample request:

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


Sample response:

  {
  …
  {
    "id": "224017",
    "name": "Kod producenta",
    "type": "string",
    "required": false,
    "unit": null,
    "requiredForProduct": true
    "options": {
        "variantsAllowed": false,
        "variantsEqual": false,
        "ambiguousValueId": null,
        "dependsOnParameterId": null,
        "describesProduct": true
    },
    "restrictions": {
        "minLength": 2,
        "maxLength": 35,
        "allowedNumberOfValues": 1
    }
 },
 {
    "id": "202685",
    "name": "Typ",
    "type": "dictionary",
    "required": true,
    "unit": null,
    "requiredForProduct": true
    "options": {
        "variantsAllowed": true,
        "variantsEqual": false,
        "ambiguousValueId": "202685_385861",
        "dependsOnParameterId": null,
        "describesProduct": true
    },
    "dictionary": [
        {
            "id": "202685_212929",
            "value": "Smartfon",
            "dependsOnValueIds": []
        },
        {
            "id": "202685_212933",
            "value": "Telefon komórkowy",
            "dependsOnValueIds": []
        },
        {
            "id": "202685_385861",
            "value": "inny",
            "dependsOnValueIds": []
        }
        ],
    "restrictions": {
        "multipleChoices": false
    }
  },
 ...
 }

You can also use GET /sale/categories/{categoryId}/product-parameters to retrieve suitable parameters.


Sample request for category 79153 - Fantasy

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


Sample response

 {
  "parameters": [                       -- parameters available to create a product
    {
      "id": "223545",                   -- parameter ID
      "name": "Tytuł",                  -- parameter name
      "type": "string",                 -- parameter type - e.g. string
      "required": true,                 -- is the parameter required to create the product
      "unit": null,                     -- unit describing parameter value
      "restrictions": {                 -- restrictions applied to string parameters
        "minLength": 1,                 -- minimum number of characters
        "maxLength": 200,               -- maximum number of characters
        "allowedNumberOfValues": 1      -- number of values to be provided for a given parameter
      }
    },
 ...
    {
      "id": "75",                       -- parameter ID
      "name": "Okładka",                -- parameter name
      "type": "dictionary",             -- parameter type - e.g. dictionary
      "required": true,                 -- is the parameter required to create the product
      "unit": null,                     -- unit describing parameter value
      "dictionary": [                   -- value of the dictionary parameter
        {
          "id": "75_1",                 -- value ID
          "value": "miękka"             -- value
        },
        {
          "id": "75_314838",
          "value": "inna"
        }
      ],
      "restrictions": {                 -- restrictions applied to dictionary type parameters
        "multipleChoices": false        -- does the parameter support many values
      }
    },
    {
      "id": "74",                       -- parameter ID
      "name": "Rok wydania",            -- parameter name
      "type": "integer",                -- parameter type - e.g. integer
      "required": true,                 -- is the parameter required to create the product
      "unit": null,                     -- unit describing parameter value
      "restrictions": {                 -- restrictions applied to integer parameters
        "min": 1400,                    -- minimum value
        "max": 2099,                    -- maximum value
        "range": false                  -- does the parameter support range of values
      }
    },
 ...
    {
      "id": "223333",                   -- parameter ID
      "name": "Szerokość produktu",     -- parameter name
      "type": "float",                  -- parameter type - e.g. float
      "required": false,                -- is the parameter required to create the product
      "unit": "cm",                     -- unit describing parameter value
      "restrictions": {                 -- restrictions applied to float parameters
        "min": 1.0,                     -- minimum value
        "max": 250.0,                   -- maximum value
        "range": false,                 -- does the parameter support range of values
        "precision": 2                  -- number of places after a comma that can be transferred
                                        in the parameter value
 }}]}

Add your own value for parameter with ambiguous value

Ambiguous value is for example “other” in the parameter “Brand”. You can retrieve its identifier via GET /sale/categories/{categoryId}/parameters in options section - field ‘ambiguousValueId’. You can find more information about ambiguousValueId in our news.

Check the ambiguousValueId field in selected category via GET /sale/categories/{categoryId}/parameters:

   {
    "parameters": [
    {
        "id": "129033",
        "name": "Marka",
        "type": “dictionary”,
        "required":true,
        "unit": null,
        "requiredForProduct": true
        "options": {
                "variantsAllowed": false,
                "variantsEqual": true,
                "ambiguousValueId": "129033_13",        -- identifier for ambiguous value,
                                                        in this case it is “other”
                "dependsOnParameterId": null,
                "requiredDependsOnValueIds": null,
                "displayDependsOnValueIds": null,
                "describesProduct": false,
                "customValuesEnabled": false            -- whether you can provide your own                 
                                                        value in a given parameter
     },
        ...
     }

Provide following structure in the parameters section. You can find a current list of parameters, to which you can add your own value, on our sellers page. If you provide an ambiguous value identifier in the valuesIds field, it is mandatory to fill in your own value in the values field.

   {
        "id": "129033",                                  -- parameter id
        "valuesIds": [
         "129033_13"                                     -- ambiguous value id
        ],
        "values": [ "Name of the missing brand" ],       -- value, which you want to provide.
                                                           Complete this field.
        "rangeValue": null
    }

Upload photos to depict the product

Call POST /sale/images to upload photos via HTTP and HTTPS protocols to our servers. There are two upload methods:

  • link

  • binary format.

The response will contain address of the photo you can use for creating the product. For more information, go to Listing offers tutorial.

information
  • You must add at least one photo to a product, but no more than 16.
  • Product photos must meet the same rules as offer photos.

Describe the product

In a similar way, as the offer, you can describe the product. The same rules apply to the product description as to the offer description. You can find detailed information about the structure of the description, elements of the description and applicable characters in Listing offers tutorial.

Add a product proposal

information

Use POST /sale/product-proposals to create a product proposal. Provided data is verified by our team. Accepted details of provided product are available to be assigned to an offer. Some data is accepted automatically, some manually - which may take some time.

When you want to assign the product to an offer, call GET /sale/products/{productId} to find out which product details has been accepted and are available to be used in an offer.

To propose a product, you need the following data:

  • suggested product name

  • category

  • parameters and their values

  • photos

  • (optional) product description

and transfer it by calling POST /sale/product-proposals. The response will contain a product ID.


The name field is a suggested product name. Depending on a category and provided parameter values:

  • the name is created automatically based on parameters;

  • the name is created based on the value provided in the name field.

The response will include the final name of the product. See a sample request and response below the Adding products - terms and rules.

information

Identifying duplicates

When you create a product, we verify its parameters and EAN code. If we find a duplicate, you will receive the status HTTP 409 - Conflict. The address of the existing product will be provided in the location header.

Adding product - terms and rules

Each time you call POST /sale/product-proposals it means you agree to comply with and be legally bound by the terms and rules below. Soon, we will also include them in Allegro User Agreement.

  1. Only users of fully activated accounts can add products.
  2. Product data is verified by Allegro.pl to eliminate any errors or unlawful content.
  3. A user adds the product in good faith and with due care. At the same time, the user represents that to their best knowledge product data is real and describes the product accurately.
  4. After adding a product, the user grants Allegro.pl authorization and consent referred to in 5.1 and 5.5 of Allegro User Agreement sregarding all content and elements added. Moreover, the user also cannot edit the product. If necessary, you can submit a request for editing product data via contact form.
  5. Allegro.pl is not obliged to use the product and does not have to display it. The product can be deleted, replaced with other product or the product data can be edited. The user introducing the product is not granted any special rights to the product.


Click to view sample request:
curl -X POST 
https://api.allegro.pl/sale/product-proposals’
-H 'Authorization: Bearer {token}'
-H 'Content-Type: application/vnd.allegro.public.v1+json'
-H 'accept: application/vnd.allegro.public.v1+json'
-d '{ "name": "Świat Lodu i Ognia George R. R. Martin i inni", – required; recommended product name (up to 50 characters) "category": {
"id": "79157" – required, category ID }, "parameters": [ – required, array of product parameters { "id": "223545", – required, parameter ID "values": "Świat Lodu i Ognia" – value of string parameter }, { "id": "223489", "values": [ – values of string parameter with "Elio M. García. Jr.", multiple values ((author in this case) "George R. R. Martin", – "Linda Antonsson" ] }, { "id": "75", "valuesIds": "75_2" – value of dictionary parameter
}, { "id": "74", "values": "2014" – value of integer parameter }, { "id": "24648", "valuesIds": [ – values of dictionary parameter "24648_1", with multiple values (edition in this case) "24648_2" ] },
{ "id": "223333", "values": [ – value of float parameter "20.5" (product width in this case) ] }, { "id": "245669", – GTIN parameter "name": "ISBN", "valuesLabels": [ "9788380082434" ], "values": [ "9788380082434" – GTIN parameter value (via GET /sale/categories/{categoryId}/parameters check in a field requiredForProduct in GTIN parameter, whether you need to provide minimum one value of GTIN parameter) ], "unit": null, "options": { "identifiesProduct": true, "isGTIN": true } } ], "images": [ – required at least 1, product photos { "url": "https://a.allegroimg.com/original/03d68a/6092f8024506a01087c820e58f0c&#34; } ], "description": { – product description "sections": [ { "items": [ { "type": "TEXT", "content": "<p>Opis produktu</p>" } ] } ] }}'

FAQ

I have not found a suitable product. How can I assign offers to the offered product?

  • Make sure you have provided correct input data when calling GET /sale/products.

  • We still work on the product database – repeat the call after a moment and check if the product is available in our database.

  • Add a product by calling POST /sale/product-proposals.


What will happen if I transfer different parameter values then the one I received for a product?

An error in the “validation” field will occur indicating the parameter value that does not match the product.


Can a customer use product data retrieved by calling GET /sale/products/{productId} somewhere else, e.g. in a store?

No, because of the copyrights. The data can be used only on Allegro.


Categories that support creating products and categories that support assigning offers to products – are they different?

Yes, they may be different. Some categories may support only adding products because we are still building the database. However, it may also happen that you can use only products from the database to assign offers with a product, but without creating a product.


What should I do if I need to edit or update the product data?

Submit a request for editing product data via contact form. Eventually, we will introduce separate resources for requesting product updates. Such requests are verified and – if justified – suitable changes will be introduced.


Can I remove a product?

No, and we do not plan introducing such options.

List of resources

You will find full documentation of resources in the swagger.yaml form file here.

List of basic resources used in tutorial:

List of supporting resources used in tutorial: