Disputes



The main purpose of the discussion is to help the buyer solve the problem, with the support of the seller. We enable sellers to use our disputes resources in REST API. Thanks to this, sellers can easily contact buyers and solve any transaction problem conveniently and quickly.

You will find more information about Disputes in Allegro Help.

All Disputes

Using GET /sale/disputes you will retrieve all disputes. You must be logged into a seller account.


Sample request:

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


Click to view sample response:
{
    "disputes": [
        {
            "id": "a38812fa-6fef-4c9c-ac06-a0952b67ba78",       – dispute ID
            "subject": {
                "name": "przedmiot jest uszkodzony"             – reason for dispute,
                                                                supported values
            },
            "status": "ONGOING",                                – dispute status,
                                                                supported values:
                                                                “ONGOING”, “CLOSED”,
                                                                “UNRESOLVED”
            "buyer": {
                "id": "3952032",                                – Buyer ID
                "login": "Buyer_login1"                         – Buyer username
            },
            "checkoutForm": {
                "id": "31fc03c3-9ebc-11e8-8885-2bfbcd0aa7ab",   – order ID
                "createdAt": "2018-08-13T05:46:56.000Z"         – order creation date
            },
            "message": {                                        – first message in the discussion
                "id": "e75d97ba-18a7-4d1b-a7ee-d02ba1a21bba",   – message ID
                "text": "Niestety towar jest uszkodzony.",      – message content
                "attachment": {                                 – dispute attachment
                    "fileName": "Zrzut ekranu.png",             – file name
                    "url": "https://upload.allegro.pl/sale/     – file path
dispute-attachments/731f2401-7b79-4212-be9e-591464526cfe"
                },
                "author": {
                    "login": "Buyer_login1",
                    "role": "BUYER"                             – role of a message author:
                                                                BUYER, ADMIN
                },
                "createdAt": "2018-09-14T06:34:24.258Z"         – dispute creation date
            },
            "messagesCount": 5                                  – number of messages within
                                                                a dispute
        },
        {
            "id": "a6f45545-16a6-4ede-b689-aa105b184229",
            "subject": {
                "name": "przedmiot jest uszkodzony"
            },
            "status": "UNRESOLVED",
            "buyer": {
                "id": "42334554",
                "login": "Buyer_login2"
            },
            "checkoutForm": {
                "id": "3add96b0-734f-11e6-9999-2be182b71611",
                "createdAt": "2016-09-05T09:58:01.000Z"
            },
            "message": {
                "id": "8de2dd79-75c6-4f35-ba5f-5ddf2c4f699a",
                "text": "dostałem nadgryziony produkt",
                "author": {
                    "login": "Buyer_login2",
                    "role": "BUYER"
                },
                "createdAt": "2016-09-20T11:09:20.659Z"
            },
            "messagesCount": 6
        }
    ]
}

You can search by parameters:

  • limit - to specify the number of messages on the list (minimum 1, max. 100),

  • offset - to indicate the place from which you want to download another portion of data (minimum 0); for example: GET /sale/disputes?limit=4&offset=5

  • checkoutForm.id - to retrieve a dispute related to a particular order; for example: GET /sale/disputes?checkoutForm.id=31fc03c3-9ebc-11e8-8885-2bfbcd0aa7ab. Use GET /order/checkout-forms to retrieve an order number.


Sample request:

curl -X GET \
  'https://api.allegro.pl/sale/disputes?checkoutForm.id=31fc03c3-9ebc-11e8-8885-2bfbcd0aa7ab' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Authorization: Bearer {token}'


Click to view sample response:
{
    "disputes": [
        {
            "id": "a38812fa-6fef-4c9c-ac06-a0952b67ba78",       – dispute ID
            "subject": {
                "name": "przedmiot jest uszkodzony"             – reason for dispute,
                                                                supported values
            },
            "status": "ONGOING",                                – dispute status,
                                                                supported values:
                                                                “ONGOING”, “CLOSED”,
                                                                “UNRESOLVED”
            "buyer": {
                "id": "3952032",                                – Buyer ID
                "login": "Buyer_login1"                         – Buyer username
            },
            "checkoutForm": {
                "id": "31fc03c3-9ebc-11e8-8885-2bfbcd0aa7ab",   – order ID
                "createdAt": "2018-08-13T05:46:56.000Z"         – order creation date
            },
            "message": {                                        – first message in the discussion
                "id": "e75d97ba-18a7-4d1b-a7ee-d02ba1a21bba",   – message ID
                "text": "Niestety towar jest uszkodzony.",      – message content
                "attachment": {                                 – dispute attachment
                    "fileName": "Zrzut ekranu.png",             – file name
                    "url": "https://upload.allegro.pl/sale/     – file path
dispute-attachments/731f2401-7b79-4212-be9e-591464526cfe"
                },
                "author": {
                    "login": "Buyer_login1",
                    "role": "BUYER"                             – role of a message author:
                                                                BUYER, ADMIN
                },
                "createdAt": "2018-09-14T06:34:24.258Z"         – dispute creation date
            },
            "messagesCount": 5                                  – number of messages within
                                                                a dispute
        }
    ]
}

Information about a particular dispute

Using GET /sale/disputes/{disputeId} you will retrieve information about a particular dispute. You must be logged into a seller account.

information Note! “DisputeId” field is a parameter that you can find in Discussions with Buyers tab or retrieve by calling GET /sale/disputes.


Sample request:

curl -X GET \
  https://api.allegro.pl/sale/disputes/a38812fa-6fef-4c9c-ac06-a0952b67ba78 \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Authorization: Bearer {token}'


Click to view sample response:
{
    "id": "a38812fa-6fef-4c9c-ac06-a0952b67ba78",           – dispute ID
    "subject": {
        "name": "przedmiot jest uszkodzony"                 – reason for dispute,
                                                            supported values
    },
    "status": "ONGOING",                                    – dispute status,
                                                            supported values:
                                                            “ONGOING”, “CLOSED”,
                                                            “UNRESOLVED”
    "buyer": {
        "id": "3952032",                                    – Buyer ID
        "login": "Buyer_login1"                             – Buyer username
    },
    "checkoutForm": {
        "id": "31fc03c3-9ebc-11e8-8885-2bfbcd0aa7ab",       – order ID
        "createdAt": "2018-08-13T05:46:56.000Z"             – order creation date
    },
    "message": {                                            – first message in the discussion
        "id": "e75d97ba-18a7-4d1b-a7ee-d02ba1a21bba",       – message ID
        "text": "Niestety towar jest uszkodzony.",          – message content
        "attachment": {                                     – dispute attachment
            "fileName": "Zrzut ekranu.png",                 – file name
            "url": "https://upload.allegro.pl/sale/         – file path
dispute-attachments/731f2401-7b79-4212-be9e-591464526cfe"
        },
        "author": {
            "login": "Buyer_login1",
            "role": "BUYER"                                 – role of a message author:
                                                            BUYER, ADMIN
        },
        "createdAt": "2018-09-14T06:34:24.258Z"             – dispute creation date
    },
    "messagesCount": 5                                      – number of messages within
                                                            a dispute
}

All messages within a dispute

Using GET/sale/disputes/{disputeId}/messages you will retrieve all messages within a dispute. You must be logged to a seller account. We return messages from the newest to the oldest.

To limit the search result you can use the parameters:

  • limit - to define a number of messages on a list (min. 1, max. 100),

  • offset - to define a starting point for retrieving another batch of data (min. 0); for example: GET /sale/disputes/{dispute.Id}/messages?limit=4&offset=5


Click to view sample response:
{
    "messages": [
        {
            "id": "657fc2c1-addf-416a-8129-e2b55740248b",   – message ID
            "text": "Vestibulum eu interdum ex, p…",      – message content
            "author": {
                "login": "Seller_login1",                   – message author login
                "role": "SELLER"                            – role of a message author:
                                                            BUYER, ADMIN, SELLER
            },
            "createdAt": "2018-09-14T06:36:55.332Z"         – creation date
        },
        {
            "id": "8586fa58-ff19-4713-8b3e-9c0c3ff73e1b",
            "text": "Lorem ipsum …",
            "author": {
                "login": "Buyer_login1",
                "role": "BUYER"
            },
            "createdAt": "2018-09-14T06:36:40.100Z"
        },
        {
            "id": "3f730fe3-f2d4-4548-a722-b81c27acd282",
            "text": "Proszę o szczegóły…",
            "author": {
                "login": "Seller_login1",
                "role": "SELLER"
            },
            "createdAt": "2018-09-14T06:36:14.270Z"
        },
        {
            "id": "10d392e2-6ea7-4347-9baf-5fe54a9580e8",
            "text": "Czy mogę prosić o wymianę?",
            "author": {
                "login": "Buyer_login1",
                "role": "BUYER"
            },
            "createdAt": "2018-09-14T06:34:44.439Z"
        },
        {
            "id": "e75d97ba-18a7-4d1b-a7ee-d02ba1a21bba",
            "text": "Niestety towar jest uszkodzony.",
            "attachment": {                                 – dispute attachment
                "fileName": "Zrzut ekranu.png",             – file name
                "url": "https://upload.allegro.pl/sale/     – file path
dispute-attachments/731f2401-7b79-4212-be9e-591464526cfe"
            },
            "author": {
                "login": "Buyer_login1",
                "role": "BUYER"
            },
            "createdAt": "2018-09-14T06:34:24.258Z"
        }
    ]
}

Add a new message in the discussion

Use POST /sale/disputes/{disputeId}/messages to add a message to a dispute.

Message can have two types:

  • REGULAR is a message related to a dispute that includes text, attachment or both.

  • END_REQUEST is “ASK FOR CLOSING THE DISPUTE”.


Sample request:

curl -X POST \
  https://api.allegro.pl/sale/disputes/a38812fa-6fef-4c9c-ac06-a0952b67ba78/messages \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/vnd.allegro.public.v1+json' \
  -d '{
"text": "Lorem ipsum dolor sit amet,                -- required; if no attachment
                                                    is added "attachment"
consectetur adipiscing elit.\n\n\n  
Pellentesque tincidunt, lacus nec interdum pellentesque.",
"attachment":{
    "id": "77b2f474-0b87-4b68-9297-56676bc84a6c"    -- required (if you do not send the text field);
                                                    you can retrieve attachment ID by calling
                                                    POST /sale/dispute-attachments/
},
"type": "REGULAR"                                   -- required, message types:
                                                    REGULAR and END_REQUEST
}'


Click to view sample response:
{
    "id": "962e051e-2509-4ccf-910d-5e5179b975b9",
    "text": "Lorem ipsum dolor sit amet,
    consectetur adipiscing elit.\n\n\n
Pellentesque tincidunt, lacus nec interdum pellentesque.", "author": { "login": "Seller_login1", "role": "SELLER" }, "createdAt": "2018-09-17T05:20:56.692Z" }

Attachments


In our API we provide three resources responsible for managing attachments in disputes:

Using GET /sale/dispute-attachments/{attachmentId} you will retrieve a particular attachment related to the dispute. You will find “attachmentId” in the “attachment.url” field when you use one of the resources listed :


Sample request:

curl -X GET \
  https://api.allegro.pl/sale/dispute-attachments/66377da8-eee2-4094-8dcf-3540e51c307f \
  -H 'Authorization: Bearer {token}'


Click to view sample response:
{
…
 "message": {
        "id": "657fc2c1-addf-416a-8129-e2b55740248b",
        "text": "Vestibulum eu interdum ex, p…",
        "attachment": {
            "fileName": "test.jpg",
            "url": "https://upload.allegro.pl/sale/dispute-attachments/95d066c1-ac44-4c7e-8a7f-0c074b848c6e"
        }
…
}

Attachment declaration

Using POST /sale/dispute-attachments you will send an attachment declaration and define its size (in bytes) and name. In response you will receive:


Sample request:

curl -X POST \
  https://api.allegro.pl/sale/dispute-attachments \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/vnd.allegro.public.v1+json' \
  -d '{
    "size": 2549,                           -- wymagane, rozmiar pliku
    "fileName": "Zrzut_ekranu.png"          -- wymagane, nazwa pliku
}'


Click to view sample response:
{
    "id": "77b2f474-0b87-4b68-9297-56676bc84a6c"
}

Adding an attachment

Use PUT https://upload.allegro.pl/sale/dispute-attachments/{attachmentId} to upload the attachment to our server. Please provide its ID in your request. You will retrieve the attachment ID with POST /sale/dispute-attachments. As content-type, provide the type of file you want to add:

  • image/png,

  • image/gif,

  • image/bmp,

  • image/tiff,

  • image/jpeg,

  • application/pdf.

information Note! You must send the attachment in binary form.


Sample request:

curl -X PUT \
  https://upload.allegro.pl/sale/dispute-attachments/66377da8-eee2-4094-8dcf-3540e51c307f \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: image/png'

List of resources


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

List of basic resources used in tutorial: