REST API

The Allegro platform provides customers with API features based on the REST architecture. For this purpose it uses the HTTP protocol and its methods: GET, POST, PUT, PATCH, DELETE. Allegro platform elements have been divided into resources e.g. /sale/offers, /sale/categories, /order/checkout-forms, etc. You can access them by calling a selected HTTP method at https://api.allegro.pl, adding a path to a selected resource.

Example of loading information on Allegro category with identifier 2:

 GET https://api.allegro.pl/sale/categories/2

If you want to load more than one resource, do not enter the identifier in the path. Example loading of Allegro category list:

 GET https://api.allegro.pl/sale/categories

Note! If you want to download documentation of the resources in the form of swagger.yaml click here.

HTTP methods

Each of the API resources can use the following HTTP methods:

  • GET: Used for data loading. All GET methods can be called several times, because they do not modify any Allegro resources.
  • POST: Used for creating a new resource (e.g. creating a new offer draft results in a resource of /sale/offers). If the POST method is called twice on /sale/offers, two offer drafts will be created on Allegro.
  • PUT: Used for editing a resource (e.g. editing a description of an Allegro offer). It is secure to call the PUT method twice on the same resource.
  • PATCH: Used for partial editing of a resource (e.g. price editing, without sending the entire offer structure).
  • DELETE: Used for deleting resources.

Communication protocol

REST API can be accessed by HTTPS connection to the api.allegro.pl server. All data sent and loaded from the server is in the JSON format.

 $ curl -i https://api.allegro.pl

 HTTP/1.1 404 Not Found
 Connection: keep-alive
 Trace-Id: 99436185-4d7c-483b-a594-e56cbfcec360
 Content-Type: application/json; charset=utf-8
 Content-Length: 165
 Date: Tue, 08 Sep 2015 07:59:45 GMT
 X-Frame-Options: SAMEORIGIN

 {"errors":[{"code":"NotFoundException","message":"Not found","details":null,"path":null,"userMessage":"Function not available. Contact the application author."}]}

Each response contains e.g. Trace-Id header whose value clearly identifies the customer’s HTTP query. If a problem is reported with the HTTP query, it is necessary to provide Trace-Id in the request.

Data representation (JSON)

All data is sent and loaded from API in the JSON format. The basic element of this format is a field whose name is separated by a colon from the field value. Fields are separated by a comma. A JSON object is another element, enclosed in double curly brackets. Tables in the JSON format are saved using square brackets. Empty fields (with null value) are each time attached to the response – they are not hidden.

 {
  "offers": [
    {
      "id": "123",
      "title": "test"
    },
    {
      "id": "456",
      "title": null
    }
  ]
 }

Access to API

You will be granted access to API after registering your application.

Authentication and authorization

All REST API resource requests require an OAuth token to be provided in the Authorization header. For more information on the OAuth authorization, read the article dedicated to this issue.

Parameters

A number of API methods can accept optional parameters. HTTP queries of the GET type accept parameters placed in the address of the resource which the query refers to. If a parameter name corresponds to the field inside the object, parts of this name are separated by dots:

 https://api.allegro.pl/sale/offers?product.id.empty=true

Other HTTP query types, such as POST and PUT, have parameters placed in the query itself, and not in the address:

 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": "Suszarka do włosów z dyfuzorem jonizacja",
     "category": {
         "id": "257150"
 }

DELETE queries do not accept parameters placed in their contents, but it may happen that they will accept parameters in the resource address.

Resource versioning

REST methods are versioned. Any changes to them violating backwards compatibility are introduced to new method versions. When calling the method, you need to enter a resource version number (which can be viewed in the method documentation).

Choose the method version by setting e.g. v1 in the Accept or Content-Type headers:

 application/vnd.allegro.public.v1+json

Exceptions include DELETE and end-point OAuth methods (https://allegro.pl/auth) which are not versioned.

Beta version methods

Beta version methods are resources we are still working on. They may not be fully functional, may be often changed and violate backwards compatibility.

A method in its beta version is marked similarly to a live version. The only difference is that data type contains the beta word:

 application/vnd.allegro.beta.v1+json

Resources in this version are marked accordingly in the documentation.

Example of calling a resource in the first, stable version:

 https://api.allegro.pl/sale/delivery-methods \
 -H 'Authorization: Bearer {token}' \
 -H 'accept: application/vnd.allegro.beta.v1+json'

Example of calling a resource in the second, beta version:

 https://api.allegro.pl/sale/delivery-methods \
 -H 'Authorization: Bearer {token}' \
 -H 'accept: application/vnd.allegro.beta.v2+json'

Language version

If you want to be sure that all the texts will be returned in Polish, send the following header with each request:

 Accept-Language: pl-PL

If you prefer English, send the header:

 Accept-Language: en-US

HTTP status codes

Each API request returns an HTTP status informing about the processing result. The list below presents most often used statuses:

  • 200 OK: Returned if the GET and PUT methods are successful.
  • 201 Created: It confirms that a document was created using the POST method.
  • 202 Accepted: It defines that a request has been accepted by the server, but it is still processed (it refers to asynchronous processing).
  • 204 No Content: Returned if the operation is successful, when a request does not return any data (e.g. DELETE method).
  • 304 Not Modified: It means there are no changes to the HTTP request - no redirection.
  • 400 Bad Request: Incorrect JSON data was sent.
  • 401 Unauthorized: User is not authenticated: he should log on to Allegro again and, then, call the request again.
  • 403 Forbidden: The user is authenticated, but has no rights to a particular resource.
  • 404 Not Found: The resource under query does not exist in API.
  • 406 Not Acceptable: A data type not supported by the resource was sent in the Accept header.
  • 415 Unsupported Media Type: A data type not supported by the resource was sent in Content-Type header.
  • 422 Unprocessable Entity: Incorrect field values were sent, e.g. object validation returned an error or a field does not meet the criteria imposed by the resource.
  • 429 Too Many Requests: The user has sent too many requests in a given amount of time.
  • 503 Service Unavailable: It is not possible to connect to the service.

Error handling

Each incorrect API calling is indicated by an HTTP response status higher than or equal to 400. We distinguish two formats of error response.

First of them will appear when there is some kind of a problem regarding to your request:

 {
    "errors": [
        {
            "code": "NotAcceptableException",
            "message": "An error has occurred",
            "details": null,
            "path": null,
            "userMessage": "Żądanie zawiera błędne dane. Skontaktuj się z autorem aplikacji."
        }
    ]
 } 

These type of errors are described with the following fields:

  • message: Internal information about an error for software developer. It makes it easier to find the reason for the problem.
  • code: Error code represented as a string. On its basis an application can decide whether an error requires special handling (e.g. presenting a CAPTCHA dialogue if an incorrect access password is entered).
  • userMessage: Information on an error, friendly for an application user; in most cases, this error will be addressed by presenting a field message to the user.
  • path: Path to the field containing an error (it is shown for field validation and parameter errors).
  • details: Error details (if available).

However, you may also encounter a shorter version of response body, connected with OAuth2 standard. You will get that error when some problems concerning authorization occur, i.e. no token in request or token was invalid.

You will find more information about OAuth2 specification in our tutorial and in OAuth2 RFC specification

 {
        "error": "unauthorized",
        "error_description": "Full authentication is required to access this resource"
 }

This type of errors are described with the following fields:

  • error: Error code from OAuth2 specification.
  • error_description: Additional information describing the error in a human-readable format.

Note: This format occurs only with 401 Unauthorized responses.

Pager

To load a specific result list page, you need to use two parameters:

  • offset: it defines a number of a batch of returned data and is numbered from 0.
  • limit: it defines a number of elements on the page, which cannot be higher than the maximum limit supported by the resource.

Example of loading the first batch of offers:

 GET /sale/offers?limit=100&offset=0

Example of loading another batch of offers:

 GET /sale/offers?limit=100&offset=100

Filtering options

Resources available in API may filter, which involves sending field names to be filtered in parameters placed in the resource address (query parameters).

Example of loading my all active offers:

 GET /sale/offers?publication.status=ACTIVE

Sorting options

To start searching with sorting options, you need to send the sort parameter when calling a resource (assuming that the resource supports sorting of its result list). If the sorting result is to be reversed, the field name should be preceded with a dash. If the result is to be sort by more than one field, you need to send a list of fields separated by commas in the parameter.

Example of loading an offer list sorted in ascending order by number of sold items:

 GET /sale/offers?sort=stock.sold

Example of loading an offer list sorted in descending order by number of sold items:

 GET /sale/offers?sort=-stock.sold

Example of loading an offer list sorted first by number of sold items (descending) and, then, by number of available items (ascending):

 GET /sale/offers?sort=-stock.sold,stock.available

Date and time

All the date and time fields are presented in the ISO 8601 standard:

 YYYY-MM-DDTHH:MM:SSZ

There is a time difference between the date we present in My Allegro and the REST API due to different time zones:

  • REST API: +00:00Z - “Zulu Time”, universal time;
  • My Allegro: +01.00 or +02:00 (depending on the time zone, +01:00 is for Central European Time, +02:00 is for Central European Summer Time) local time zone.

Note! Some fields, e.g. “handlingTime” or “duration”, require from you specify form of time - for example: P3D (3 days); P5D (5 days); P7D (7 days). Before completing the structure check the available values for fields resource documentation.

Price and currency

The price and currency are sent and returned as two fields:

  • amount: A string of characters representing a numerical value – price.
  • currency: A three-letter currency code compliant with ISO 4217.

Example:

 {
  "buyNowPrice": {
    "amount": "10.23",
    "currency": "PLN"
  }
 }

Resource IDs

API returns resource identifiers always as a string of characters, mostly in the UUID format. We recommend that identifiers be stored in strings, even if API returns a number in inverted commas as an identifier, because it may change in the future.

Example:

 "bg645d84-75b4-431b-adb2-eb6b9e546059"

Note! If you use resources that require {commandId}, such as PUT /sale/offer-modification-commands/{commandId} in commandId field, indicate ID on which we will save this request.

CommandId is the identifier of a given request, on its basis you can check status of your request. For example, use resource such as GET /sale/offer-modification-commands/{commandId}.

Remember that the commandId must be unique. We require identifiers in the UUID standard.

For more information click here.

Limiting the number of queries (limits)

In Allegro REST API (production and test) there is one main limit imposed on Client ID - 9000 requests per minute.

If the limit is exceeded:

  • the Client ID is blocked for a minute,
  • a response is returned with the following status: 429 Too Many Requests.

When the specified time limit expires, the access to the service from the Client ID is restored automatically.

For some resources, we apply additional, lower limits of the number of requests. In such cases, you can find information about the additional limit in the resource description in Allegro REST API documentation.

Leaky Bucket

Selected REST API resources have a mechanism that limits the number of requests submitted by a given user (user.id). We use the Leaky Bucket algorithm. If the user exceeds the number of requests per minute (RPM), the response time is extended. In the event of too many parallel requests submitted on behalf of the same user, the server will return HTTP error: 429 Too Many Requests.

Test environment

What is Sandbox?

Allegro Sandbox is a test environment. Use it to test, in a secure manner, REST API supported by Allegro. The environment reflects all the major features of Allegro. It means you can:

  • activate an account,
  • list an offer,
  • go through a customer journey,
  • use a search engine,
  • rate a seller.

With a built-in simulator you can also test quick online payments.

How does it work?

Sandbox mirrors features of the live environment. Use the test environment as you would use allegro.pl:

The test environment is available to all. To get constant access to the environment, visit this address, click on “Załóż konto” (“Create an account”), and after that activate it.

Remember to provide real address data during activation. By real data, we mean data that matches, e.g.:

  • street: Grunwaldzka 182,
  • postal code: 60-166,
  • city: Poznań.

Otherwise, the activation may fail.

The test environment is a separate one. If you have issues activating your account, please contact us on our forum.

Differences between live and test REST API:

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/

Note!

  • Observe the rules of our test environment.
  • Remember to query appropriate resource address.
  • The test environment is subject to the same limits of number of calls as the live one.
  • Technical breaks will be announced in REST API news.
  • We will remove uploaded photos after 7 days.
  • We update the list of categories and parameters once a quarter. Due to this, we remove all offers from Sandbox.
  • Email notifications sent from Sandbox have the title “Message from WebAPI Sandbox environment” and the content of the notification itself is attached in the .eml file in the message.

Test environment - Terms of Use

Rules for using test version of Allegro API

  1. You can test free of charge Allegro API (REST API) within one environment (“Service”) at allegro.pl.allegrosandbox.pl.
  2. The Service is provided by Allegro.pl sp. z o.o. with its registered office in Poznań, at ul. Grunwaldzka 182, 60-166 Poznań, entered into the Register of Entrepreneurs kept by the District Court for Poznań – Nowe Miasto and Wilda in Poznań, 8th Commercial Department of the National Court Register under KRS number: 0000635012, share capital: PLN 33,016,950, tax identification number NIP: 525-26-74-798, statistical number REGON: 365331553 (“Allegro.pl”).
  3. By using the Service, you agree to comply with and be legally bound by the terms and conditions of these Terms of Use.
  4. The Service allows you to familiarize yourself with the way the Service is provided.
  5. Allegro.pl informs, and you acknowledge to have understood and accepted it that data used within the Service is not subject to any backup.
  6. Allegro.pl has the right to remove all data you process using the Service, in particular if you infringe the Terms of Use.
  7. You cannot use the Service to process materials whose content is unlawful, in particular materials that are or contain viruses or other software whose use would violate the law.
  8. Moreover, you cannot perform any activity that would affect the security of Allegro IT systems or IT systems of third parties, and perform activities that would affect the performance of or overload the IT systems that are involved in providing the Service in a direct or indirect manner. The actions that you can perform are security system tests, but only if they are compatible with our Bug Bounty program (hackerone.com/allegro).
  9. Remember that you are fully responsible for your actions and actions of persons with whom you shared Service data, whether intentionally or not.
  10. Allegro.pl hereby informs that it does not guarantee and shall not be held responsible for any damage caused by hindered or no access to the Service, including loss or deformation of data processed using the Service.
  11. Due to the nature and character of the Service do not provide real personal data in the forms.

Last update: October 26th, 2020