Orders in Allegro REST API
Processing orders in Allegro REST API
Events have values that indicate the order stage. There are four types of values you can check in the type field:
BOUGHT - a customer made the purchase but did not pay for the order;
FILLED_IN - this event type may occur more than once if a customer fills in shipping form several times, e.g. when the payment is not completed or was cancelled; it is worth noticing that with this particular status data can change until the payment is completed;
READY_FOR_PROCESSING - a customer filled in shipping form, completed the payment (status “ended”), and selected COD or personal pickup. Once you receive this status, you can be sure that no shipping form data will change. For this reason you can:
retrieve shipping form details,
move to next steps.
BUYER_CANCELLED - buyer cancelled the order.
FULFILLMENT_STATUS_CHANGED - a seller changed the status of the order fulfillment.
AUTO_CANCELLED - order was cancelled automatically by Allegro.
Event log
Use GET /order/events to retrieve events for monitoring customer activities such as:
purchase,
filling in shipping form,
payment cancellation,
making a surcharge,
order cancellation,
fulfillment status.
Note:
there must be at least one event for each order (e.g. filling in shipping form [FILLED_IN]);
there can be several activities concerning one order (e.g. purchase, filling in shipping form, payment);
for example, you can retrieve several events READY_FOR_PROCESSING, therefore you should the logic of your order processing on checkoutForm object;
event “BUYER_CANCELLED” may appear before or after “READY_FOR_PROCESING”;
you can retrieve events from last 60 days;
to establish duplicates of events and timeline pay attention to the event type and occurredAt field;
due to technical conditions, in some cases the events can occur in an unexpected order; it means that it is possible for e.g. READY_FOR_PROCESSING event may occur before FILLED_IN one and it is not an error.
if buyer makes two separate orders from the same seller and then combine them into one payment, you will retrieve a new event with new checkoutForm.id, previous checkoutForm.id will not be available anymore. To identify this situation you can rely on lineItem.id (if one lineItem.id appears in several orders, it means that buyer combined his purchases).
How to find the newest event
Use GET /order/event-stats to retrieve information about the last event of the authorized seller.
Sample request:
curl -X GET \
'https://api.allegro.pl/order/event-stats' \
-H 'authorization: Bearer {token}' \
-H 'accept: application/vnd.allegro.public.v1+json'Sample response:
{
"latestEvent": {
"id": "1532603898317497", -- the newest event id
"occurredAt": "2018-07-26T11:18:06.715Z" -- date of this event
}
}Retrieving event logs for orders
Log on to a seller account and use GET /order/events to retrieve a list of events. If you do not provide the “limit” parameter, you will receive 100 historical events. Use event identifiers to retrieve another batches of events – call GET on /order/events?from={last_seen_event_id}. You can determine the number of events by setting the range of “limit” parameter (1-1,000), e.g. /order/events?limit=1000.
Sample request:
curl -X GET \
'https://api.allegro.pl/order/events' \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json'You will retrieve a list of events with their identifiers to retrieve order details. Sample calls:
retrieve 500 newest events after a particular event https://api.allegro.pl/order/events?limit=500&from{last_seen_event_id}
retrieve 500 historical events of a particular type (BOUGHT, FILLED_IN or READY_FOR_PROCESSING) https://api.allegro.pl/order/events?limit=500&type=READY_FOR_PROCESSING
Click to view sample response:
{
"events": [
{
"id": "1530606686803770", -- event id
"order": {
"seller": {
"id": "43473770" -- seller id
},
"buyer": {
"id": "43955752", -- customer id
"email": "example@mail.pl", -- customer’s email address
"guest": false, -- two values are supported – false
(logged-on customer) and true (guest)
"login": "example_login" -- customer login
},
"lineItems": [
{
"offer": {
"id": "6205387764", -- offer id
"name": "telewizor TV 46", -- offer title
"external": {
"id": "extid_1234" -- offer external id
}
},
"price": {
"amount": "4343", -- total payment for the order
(including discounts offered by the seller)
"currency": "PLN"
},
"id": "4db6dae0-7e9b-11e8-a346-0ff9a46a7007",
"quantity": 1, -- number of purchased items
"originalPrice": {
"amount": "4343", -- item price (without any discounts)
"currency": "PLN"
},
"boughtAt": "2018-07-03T08:31:15.615Z" -- purchased date
}
],
"checkoutForm": {
"id": "4db701f0-7e9b-11e8-a346-0ff9a46a7007",
"revision": "d8e8fca2" -- order revision
}
},
"type": "BOUGHT", -- event type
"occurredAt": "2018-07-03T08:31:15.615Z" -- event date
},
{
"id": "1530606687599190",
"order": {
"seller": {
"id": "43473770"
},
"buyer": {
"id": "43955752",
"email": "example1@mail.pl",
"guest": false,
"login": "example_login"
},
"lineItems": [
{
"offer": {
"id": "6205387764",
"name": "Telewizor tv 46",
"external": null
},
"price": {
"amount": "4343",
"currency": "PLN"
},
"id": "4db6dae0-7e9b-11e8-a346-0ff9a46a7007",
"quantity": 1,
"originalPrice": {
"amount": "4343",
"currency": "PLN"
},
"boughtAt": "2018-07-03T08:31:15.615Z"
}
],
"checkoutForm": {
"id": "4db701f0-7e9b-11e8-a346-0ff9a46a7007",
"revision": "d8e8fca2"
}
},
"type": "FILLED_IN",
"occurredAt": "2018-07-03T08:31:16.511Z"
},
{
"id": "1530606705564126",
"order": {
"seller": {
"id": "43473770"
},
"buyer": {
"id": "43955752",
"email": "example1@mail.pl",
"guest": false,
"login": "example_login1"
},
"lineItems": [
{
"offer": {
"id": "6205387764",
"name": "Telewizor tv 46"
},
"price": {
"amount": "4343",
"currency": "PLN"
},
"id": "4db6dae0-7e9b-11e8-a346-0ff9a46a7007",
"quantity": 1,
"originalPrice": {
"amount": "4343",
"currency": "PLN"
},
"boughtAt": "2018-07-03T08:31:15.615Z"
}
],
"checkoutForm": {
"id": "4db701f0-7e9b-11e8-a346-0ff9a46a7007",
"revision": "d8e8fca2"
}
},
"type": "READY_FOR_PROCESSING",
"occurredAt": "2018-07-03T08:31:34.731Z"
}
]
}Order details
Use GET /order/checkout-forms/{checkoutForm_id} to retrieve order details such as:
data of purchased offers
customer data
order status
information on payment
shipping data
invoice details
information on selected additional options.
To retrieve order IDs use GET /order/events ( ‘events_checkoutForm’ field) or GET /order/checkout-forms.
Sample request:
curl -X GET \
'https://api.allegro.pl/order/checkout-forms/{checkoutForm_id} \’
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Authorization: Bearer {token}'
The response may include order details with three different statuses depending on the stage of order processing.
Sample response for READY_FOR_PROCESSING - a customer made the payment – status “ended” or selected COD.
Click to view sample response:
{
"id": "760c0fa1-6d85-11e8-beae-39b3e51dda59", -- order id
"buyer": {
"id": "1424041", -- customer id
"email": "ymu1woaqq+54111a037@user-dev.allegrogroup.pl",
-- customer’s email address
"login": "example_login", -- customer login
"firstName": "Tomasz", -- customer name
"lastName": "Nowak", -- customer surname
"companyName": null, -- customer company name
"guest": false, -- does customer registered the account.
"personalIdentity": null, -- PESEL number
"phoneNumber": "+381 11 1111111", -- phone number from customer settings
"address": { -- address data from customer settings
"street": "Zielona 90", -- street
"city": "Poznań", -- city
"postCode": "62-111", -- postal code
"countryCode": "PL", -- country code
}
},
"payment": {
"id": "7ba94950-6d85-11e8-9fe4-e9ed44ab58af",-- payment ID
"type": "CASH_ON_DELIVERY" -- payment type “ONLINE”, “CASH_ON_DELIVERY",
"SPLIT_PAYMENT", "EXTENDED_TERM"
"provider": null,
"finishedAt": "2019-07-23T12:58:58.609Z", -- date on which shipping form
was submitted
"paidAmount": null
},
"status": "READY_FOR_PROCESSING",
"fulfillment": { -- order fulfillment status
"status": "PROCESSING"
"shipmentSummary": {
"lineItemsSent": "ALL" -- information whether the items in the order
have a tracking number. List of values can
be found in our documentation.
}
}
"delivery": { -- shipping data (in the case of
general delivery theadditional
“pickupPoint” block is displayed)
"address": {
"firstName": "Jan", -- customer name
"lastName": "Nowak", -- customer surname
"street": "Zielona 90", -- street
"city": "Poznań", -- city
"zipCode": "62-111", -- postal code
"countryCode": "PL", -- country code
"phoneNumber": "+381 11 1111111" -- phone number
"modifiedAt": null -- address modification date
},
"method": {
"id": "7203cb90-864c-4cda-bf08-dc883f0c78ad", -- shipping method ID (to
retrieve a list of methods call
GET on /sale/delivery-methods)
"name": "Przesyłka kurierska", -- shipping method name
},
"cost": {
"amount": "6.00", -- shipping cost
"currency": "PLN"
},
"smart": false -- supported values: true
(customer used a SMART option)
false (customer did not use
a SMART option)
"time": {
"guaranteed": { -- guaranteed time of delivery
"from": "2019-07-31T16:00:00Z", -- delivery time from
"to": "2019-07-31T18:00:00Z" -- delivery time to
}
},
"calculatedNumberOfPackages": null -- total number of all packages in the order
(available for orders created after 07.10.2019)
},
"invoice": { -- data about invoice
"Required": true - supported values: “false”
(customer does not want an invoice),
true (customer wants an invoice)
"address": { -- address for invoice
"street": "Zielona 90",
"city": "Poznań",
"zipCode": "62-111",
countryCode": "PL",
"naturalPerson": { -- natural person; “company” value,
“name” (company name) and tax ID
number fields will be displayed in
the case of a company
"firstName": "Jan", -- customer name
"lastName": "Testowy" -- customer surname
}
},
"lineItems": [
{
"offer": {
"id": "7335154216", -- offer ID
"name": "Telewizor 43'' KrugerMatz FULL HD SMART" -- offer title
},
"quantity": 2,
"originalPrice": {
"amount": “123.00”, -- regular offer price, before any
discounts (quantitative discounts,
sets, etc.)
"currency": "PLN"
},
"price": {
"amount": “123.00”, -- price at the moment of purchase
(including discounts, e.g. quantitative
discount, sets, etc.)
"currency": "PLN"
},
"selectedAdditionalServices": [ -- additional services
{
"definitionId": "GIFT_WRAP", -- services id
"name": "Zapakuj na prezent", -- service name
"price": {
"amount": “20.00”, -- service cost
"currency": "PLN"
},
"quantity": 2 -- number of purchased services
}
],
"boughtAt": "2018-06-11T16:41:06.793" -- purchase date
}
],
"surcharges": [],
"discounts": [ -- information about a discount
selected by the buyer
{
"type": "CROSSMULTIPACK" -- some of the items have been
subject to quantitative discounts
in different offers
},
{
"type": "MULTIPACK" -- at least one item has been subject
to a quantitative discount
},
{
"type": "BUNDLE" -- some items have been ordered
within a set
},
{
"type": "COUPON" -- a coupon has been used
}
],
"summary": {
"totalToPay": {
"amount": “292.00”, -- total payment amount (including
discount and cost of additional
services and shipping)
"currency": "PLN"
}
},
"updatedAt": "2018-06-11T16:41:06.963Z", -- checkout form last modification date
"revision": "dc0f896f" -- order revision
}Order fulfillment status change
Via PUT /order/checkout-forms/{checkoutForm.id}/fulfillment you will change the order fulfillment status, visible in the field fulfillment.status. As checkoutForm.id, provide the order number, which you can receive in response to GET /order/checkout-forms.
Sample request:
curl -X PUT
'https://api.allegro.pl/order/checkout-forms/{checkoutFormId}/fulfillment'
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.public.v1+json'
-H 'Content-Type: application/vnd.allegro.public.v1+json'
-d ‘{
"status": "SENT" -- sample values: NEW,
PROCESSING, etc.
Full list can be found in
our documentation
}’You can add optional parameter checkoutForm.revision to your request.
Sample request:
curl -X PUT
'https://api.allegro.pl/order/checkout-forms/29738e61-7f6a-11e8-ac45-09db60ede9d6/fulfillment?checkoutForm.revision=dc0f896f'
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.public.v1+json'
-H 'Content-Type: application/vnd.allegro.public.v1+json'
-d ‘{
"status": "PROCESSING"
}’
If the value of the “checkoutForm.revision” field:
will be equal to the current revision of the order in our system, the order fulfillment status will be changed;
will be different from the current revision of the order in our system (e.g. the buyer made a change of order status, payment, address, invoice data, etc.), an error with the status code 409 CONFLICT will be returned. It means that you need to retrieve a newer version of the order, because it has changed and try again to change the order fulfillment status with the new value of the “checkoutForm.revision” field.
If the seller has enabled subscription, in the Orders tab he can set automatic:
change the status to “SENT”, when a tracking number(waybill) is added,
sending a message to the buyer after the status is changed.
Order cancellation
If you have a company account and you have not changed order fulfillment status (to the “PROCESSING”, “READY_FOR_SHIPMENT”, “SENT”, “READY_FOR_PICKUP”, “PICKED UP”) or you have not added a tracking number to the order, buyer may cancel the order within 3 days after purchase. Therefore, when you start order processing, change the fulfillment status (“fulfillment.status”) each time. If the buyer cancelled an order, which is already paid, you can refund the payment via POST /payments/refunds.
Click to view sample response:
{
"id": "c6287a22-57b5-31ea-93bf-4dbbe06503ca",
"messageToSeller": null,
"buyer": {
"id": "111222333",
"email": "yuxwjq25z4+52353b6a2@allegromail.pl",
"login": "TestABC",
"firstName": "Jan",
"lastName": "Nowak",
"companyName": null,
"guest": false,
"personalIdentity": null,
"phoneNumber": "+48 700 700 700",
"address": {
"street": "Grunwaldzka 182",
"city": "Poznań",
"postCode": "60-166",
"countryCode": "PL"
}
},
"payment": {
"id": "2dae8362-57b6-11ea-97c2-b71e91a5aa42",
"type": "ONLINE",
"provider": "PAYU",
"finishedAt": "2020-05-05T10:06:39.065Z", -- date on which payment was finished
"paidAmount": { -- payment amount (if order was cancelled
"amount": "1.00", refund the payment via
"currency": "PLN" POST /payments/refunds)
}
},
"status": "CANCELLED", -- order status
"fulfillment": {
"status": "NEW",
"shipmentSummary": {
"lineItemsSent": "NONE"
}
},
"delivery": {
"address": {
"firstName": "Jan",
"lastName": "Nowak",
"street": "Grunwaldzka 182",
"city": "Poznań",
"zipCode": "60-166",
"countryCode": "PL",
"companyName": null,
"phoneNumber": "700700700"
},
"method": {
"id": "7203cb90-864c-4cda-bf08-dc883f0c78ad",
"name": "Przesyłka kurierska"
},
"pickupPoint": null,
"cost": {
"amount": "0.00",
"currency": "PLN"
},
"smart": false,
"time": {
"guaranteed": null
},
"calculatedNumberOfPackages": 1
},
"invoice": {
"required": false,
"address": null
},
"lineItems": [
{
"id": "c6287a20-57b5-11ea-93bf-4dbbe06503ca",
"offer": {
"id": "8969787034",
"name": "Test",
"external": null
},
"quantity": 1,
"originalPrice": {
"amount": "1.00",
"currency": "PLN"
},
"price": {
"amount": "1.00",
"currency": "PLN"
},
"selectedAdditionalServices": [],
"boughtAt": "2020-05-05T10:01:53.657Z"
}
],
"surcharges": [],
"discounts": [],
"summary": {
"totalToPay": {
"amount": "1.00",
"currency": "PLN"
}
},
"updatedAt": "2020-05-05T10:06:39.065Z",
"revision": "dc0f896f"
}Automatic order cancellation
If the buyer chooses to pay in advance and fails to pay for the order within 7 days, order will be automatically cancelled by Allegro. In the Order settings tab the seller can set his own time, after which we will automatically cancel unpaid orders in all offers in his account. However, it cannot be shorter than 7 days or longer than 30 days.
Note! If the buyer wins the auction and chooses to pay in advance, we will automatically cancel the order if the customer fails to pay within 30 days.
Order list
You can retrieve an order list via GET /order/checkout-forms.
Note! This resource is only for supporting managing orders. The main resource for monitoring customer activities is GET /order/eventsń. Data in resource GET /order/checkout-forms is filter by “boughtAt”. If customer pay for order later, information about that order will occur in order with “boughtAt” date, not as newest.
The list includes orders from last 6 months and returns the same set of the data, which you can find in order details. You will be able to filter it and search for particular data. You can also download an order list that meets your needs by specify parameters:
limit - set the number of orders to be returned in the response (takes values from 1-100),
offset - indicate the place from which you want to download another portion of data (takes values from 0 to the number of orders -1).
e.g. GET /order/checkout-forms?limit=10&offset=9 - will return a list of 10 orders from the given point. The sum offset and limit can not exceed 10,000.
We have made it possible to filter orders by:
Status, may include one or more values, e.g. https://api.allegro.pl/order/checkout-forms?status=BOUGHT&status=FILLED_IN
Fulfillment status, may include one or more values, e.g. https://api.allegro.pl/order/checkout-forms?fulfillment.status=NEW&fulfillment.status=PROCESSING
Payment ID, e.g. https://api.allegro.pl/order/checkout-forms?payment.id=682c64b2-3108-11e9-b62a-6d16ee003b16
Surcharge ID, e.g. https://api.allegro.pl/order/checkout-forms?surcharges.id=21f96ba2-714f-11e9-a1f2-5b017850bf22
Purchase date in iso8601 format, e.g. https://api.allegro.pl/order/checkout-forms?lineItems.boughtAt.lte=2018-07-31T08%3A48%3A14.889Z&lineItems.boughtAt.gte=2018-07-31T08%3A48%3A14.888Z
Checkout form last modification date, e.g. https://api.allegro.pl/order/checkout-forms?updatedAt.lte=2018-07-31T08%3A48%3A14.889Z&updatedAt.gte=2018-07-31T08%3A48%3A14.888Z
Information about assigned tracking numbers, e.g. GET /order/checkout-forms?
fulfillment.shipmentSummary.lineItemsSent=ALL - in response you will receive orders with a tracking number added to all items
Sample request:
curl -X GET \
'https://api.allegro.pl/order/checkout-forms'
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json'Click to view sample response:
{
"checkoutForms": [
{
"id": "000f8281-841b-11e8-ac45-09db60ede9d6", -- order id
"messageToSeller": "message", -- message from customer
"buyer": {
"id": "1424041", -- customer id
"email": "ymu1woaqq+54111a037@user-dev.allegrogroup.pl",
-- customer’s email address
"login": "example_login", -- customer login
"firstName": "Tomasz", -- customer name
"lastName": "Nowak", -- customer surname
"companyName": null, -- customer company name
"guest": false, -- does customer registered the account.
"personalIdentity": null, -- PESEL number
"phoneNumber": "+381 11 1111111", -- phone number from customer settings
"address": { -- address data from customer settings
"street": "Zielona 90", -- street
"city": "Poznań", -- city
"postCode": "62-111", -- postal code
"countryCode": "PL", -- country code
}
},
"payment": { -- informations about payment
"id": "abd30d72-9583-11e8-96ed-27298c74ae02",-- payment id
"type": "ONLINE", -- payment type, three values are supported:
“ONLINE”, “CASH_ON_DELIVERY", "SPLIT_PAYMENT"
"provider": "PAYU" -- payment provider “PAYU”, “P24”, "OFFLINE"
},
"status": "FILLED_IN", -- payment status
"fulfillment": { -- order fulfillment status
"status": "PROCESSING"
"shipmentSummary": {
"lineItemsSent": "NONE" -- information whether the items in the order
have a tracking number. List of values can
be found in our documentation.
}
}
"delivery": { -- informations about delivery
method
"method": {
"id": "5d9c7838-e05f-4dec-afdd-58e884170ba7", -- method id
"name": "Allegro Kurier24 InPost" -- delivery method id
},
"cost": {
"amount": "13.41", -- delivery price
"currency": "PLN"
},
"smart": false -- supported values: true
(customer used a SMART option)
false (customer did not use
a SMART option)
"time": {
"guaranteed": { -- guaranteed time of delivery
"from": null, -- delivery time from
"to": "2019-07-31T18:00:00Z" -- delivery time to
}
},
"calculatedNumberOfPackages": null -- total number of all packages in the order
(available for orders created after 07.10.2019)
},
"invoice": { -- informations about invoice
"required": false
},
"lineItems": [ -- informations what items are
in this order form
{
"id": "38h7b340-8583-12e8-9d53-08c966f55539",
"offer": {
"id": "6205584020", -- offer id
"name": "Perkusja dęta", -- offer title
"external": {
"id": "ext_2018_08_17" -- offer external id
}
},
"quantity": 1, -- count of items in offer
"originalPrice": {
"amount": "240.00", -- price of particular item
"currency": "PLN"
},
"price": {
"amount": "240.00", -- price
"currency": "PLN"
},
"selectedAdditionalServices": [ -- additional services
{
"definitionId": "GIFT_WRAP", -- services id
"name": "Zapakuj na prezent", -- service name
"price": {
"amount": “10.00”, -- service cost
"currency": "PLN"
},
"quantity": 1 -- number of purchased services
}
],
"boughtAt": "2018-08-01T12:09:30.044Z" -- bought date
}
],
"surcharges": [],
"discounts": [ -- information about a discount
selected by the buyer
{
"type": "CROSSMULTIPACK" -- some of the items have been
subject to quantitative discounts
in different offers
},
{
"type": "MULTIPACK" -- at least one item has been subject
to a quantitative discount
},
{
"type": "BUNDLE" -- some items have been ordered
within a set
},
{
"type": "COUPON" -- a coupon has been used
}
],
"summary": {
"totalToPay": {
"amount": "273.41", -- summary price
"currency": "PLN"
}
},
"updatedAt": "2018-08-01T12:09:30.463Z",
"revision": "dc0f896f"
},
{
"id": "39f6cc51-9583-11e8-8d53-07c966f77738",
"buyer": {
"id": "43544033",
"email": "ymuwoaqq+54221a037@user-dev.allegrogroup.pl",
"login": "example_login",
"firstName": "Andrzej",
"lastName": "Nowak",
"companyName": null,
"guest": false,
"personalIdentity": null,
"phoneNumber": "+381 11 1111111",
"address": {
"street": "Bułgarska 6991",
"city": "Poznań",
"postCode": "18-282",
"countryCode": "PL",
}
},
"status": "BOUGHT",
"fulfillment": {
"status": "PROCESSING"
"shipmentSummary": {
"lineItemsSent": "ALL" -- information whether the items in the order
have a tracking number. List of values can
be found in our documentation.
}
}
"lineItems": [
{
"id": "39f6a540-9583-11e8-8d53-07c966f77738",
"offer": {
"id": "6205584018",
"name": "Laptop Lenovo"
},
"quantity": 1,
"originalPrice": {
"amount": "3300.00",
"currency": "PLN"
},
"price": {
"amount": "3300.00",
"currency": "PLN"
},
"selectedAdditionalServices": [ -- additional services
{
"definitionId": "GIFT_WRAP", -- services id
"name": "Zapakuj na prezent", -- service name
"price": {
"amount": “10.00”, -- service cost
"currency": "PLN"
},
"quantity": 1 -- number of purchased services
}
],
"boughtAt": "2018-08-01T12:05:53.027Z"
}
],
"surcharges": [],
"discounts": [],
"summary": {
"totalToPay": {
"amount": "3310.00",
"currency": "PLN"
}
},
"updatedAt": "2018-08-01T12:05:53.963Z",
"revision": "dc0f896g"
},
{
"id": "4db701f0-7e9b-11e8-a346-0ff9a46a7007",
"buyer": {
"id": "43544066",
"email": "ymuwoaqq+54221a037@user-dev.allegrogroup.pl",
"login": "example_login",
"firstName": "Jan",
"lastName": "Nowak",
"companyName": null,
"guest": false,
"personalIdentity": null,
"phoneNumber": "+381 11 1111111",
"address": {
"street": "Bułgarska 6900",
"city": "Poznań",
"postCode": "18-282",
"countryCode": "PL",
}
},
"payment": {
"id": "abd30d72-9583-11e8-96ed-27298c74ae02", -- payment id
"type": "ONLINE", -- payment type, three values are supported:
“ONLINE”, “CASH_ON_DELIVERY", "SPLIT_PAYMENT"
"finishedAt": "2018-07-03T08:31:34.731Z", -- payment date
"paidAmount": { -- value in payment
"amount": "4351.60",
"currency": "PLN"
}
},
"status": "READY_FOR_PROCESSING",
"fulfillment": { -- order fulfillment status
"status": "PROCESSING"
"shipmentSummary": {
"lineItemsSent": "ALL" -- information whether the items in the order
have a tracking number. List of values can
be found in our documentation.
}
}
"delivery": { -- delivery address
"address": {
"firstName": "Jan",
"lastName": "Nowak",
"street": "Rynek 1006",
"city": "Poznań",
"zipCode": "61-208",
"countryCode": "PL",
"phoneNumber": "+48 793 666 808"
},
"method": {
"id": "2488f7b7-5d1c-4d65-b85c-4cbcf253fd93",
"name": "Allegro Paczkomaty InPost"
},
"pickupPoint": {
"id": “POZ08A”,
"name": "Paczkomat POZ22N",
"description": "Przy sklepie Społem PSS",
"address": {
"street": "Oświecenia 59",
"zipCode": "61-208",
"city": "Poznań"
}
},
"cost": {
"amount": "8.60",
"currency": "PLN"
},
"smart": false,
"calculatedNumberOfPackages": null -- total number of all packages in the order
(available for orders created after 07.10.2019)
},
"invoice": {
"required": false
},
"lineItems": [
{
"id": "4db6dae0-7e9b-11e8-a346-0ff9a46a7007",
"offer": {
"id": "6205387764",
"name": “podręczniki do 1 klasy"
},
"quantity": 1,
"originalPrice": {
"amount": "4343.00",
"currency": "PLN"
},
"price": {
"amount": "4343.00",
"currency": "PLN"
},
"selectedAdditionalServices": [ -- additional services
{
"definitionId": "GIFT_WRAP", -- services id
"name": "Zapakuj na prezent", -- service name
"price": {
"amount": “10.00”, -- service cost
"currency": "PLN"
},
"quantity": 1 -- number of purchased services
}
],
"boughtAt": "2018-07-03T08:31:15.615Z"
}
],
"surcharges": [],
"discounts": [],
"summary": {
"totalToPay": {
"amount": "4361.60",
"currency": "PLN"
}
},
"updatedAt": "2018-07-03T08:31:15.963Z",
"revision": "dc0f896h"
}
],
"count": 3, -- number of orders in this response
"totalCount": 3 -- summary number of orders for seller
}Overpayment and underpayment
In some cases, a customer may pay an incorrect amount for the purchased products; in other words, there is over- or underpayment. It is easy to calculate – simply compare values of payment.paidAmount.amount and summary.totalToPay.amount.
Surcharge
In the event of a surcharge, you will find an additional block “surcharges” in details of orders with the “READY_FOR_PROCESSING” status. Surcharge structure:
Surcharge – payment is not completed:
"surcharges": [
{
"id": "5b1f4a62-6969-11e8-b090-8b2d9f391430", -- surcharge ID
"type": "ONLINE", -- values: “ONLINE”
(advance payment);
“CASH_ON_DELIVERY” (COD)
"provider": "PAYU" -- supported values: “PAYU”;
“P24” -not displayed with
“CASH_ON_DELIVERY”
}
],Surcharge – payment is completed
"surcharges": [
{
"id": "5b1f4a62-6969-11e8-b090-8b2d9f391430", -- surcharge ID
"type": "ONLINE", -- values: “ONLINE” (advance payment);
“CASH_ON_DELIVERY” (COD)
"provider": "PAYU" -- supported values: “PAYU”; “P24” -
not displayed with “CASH_ON_DELIVERY”
"finishedAt": "2018-06-06T11:11:23.351", -- payment (surcharge) date
"paidAmount": {
"amount": “12.00”, -- surcharge amount
"currency": "PLN"
}
}
],How to recognize an order covered by the Allegro Prices program
By calling GET /order/checkout-forms and GET /order/checkout-forms/{id} you will recognize orders in which price was reduced and the costs of which will be covered by Allegro Prices. In such cases, in the discounts field we will return the “ALLEGRO_PRICES” discount type.
Sample request:
curl -X GET \
'https://api.allegro.pl/order/checkout-forms/4fceac60-71c6-11eb-bb0e-5f505b61d1dc \’
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Authorization: Bearer {token}'
Click to view sample response:
{
…
"payment": {
"id": "677d4ba1-71c6-11eb-a259-c766517115fd",
"type": "ONLINE",
"provider": "PAYU",
"finishedAt": "2021-03-15T12:18:33.434Z",
"paidAmount": {
"amount": "80",
"currency": "PLN"
},
"reconciliation": null
},
"status": "READY_FOR_PROCESSING",
…
"lineItems": [
{
"id": "ffc36fa0-9584-11e8-8d53-07c966f77738",
"offer": {
"id": "6205584023",
"name": "Lifebelt",
"external": {
"id": "ext_2018_08_17"
}
},
"quantity": 1,
"originalPrice": {
"amount": "80.00",
"currency": "PLN"
},
"price": {
"amount": "80.00",
"currency": "PLN"
},
"reconciliation": {
"value": {
"amount": "20.00", – reconciliation amount
"currency": "PLN"
},
"quantity": 1, – amount of reconciled items
"type": "BILLING" – reconciliation type, one of two
values are possible:
BILLING (reconciliation for the price
reduction on billing entry);
WALLET (reconciliation for the price reduction
in buyer’s payment).
},
"selectedAdditionalServices": [ ],
"boughtAt": "2021-03-15T12:18:33.434Z"
}
],
"surcharges": [],
"discounts": [
{
"type": "ALLEGRO_PRICES" – ALLEGRO_PRICES discount type means,
that we reduced price and granted
compensation
}
],
"summary": {
"totalToPay": {
"amount": "80.00",
"currency": "PLN"
}
},
"updatedAt": "2021-03-15T12:18:33.434Z",
"revision": "dc0f896f"
}
You can recognize the type of discount for a specific item in the lineItems[].reconciliation.type field, which can return the following values:
- “BILLING” - reconciliation for the price reduction on billing entry,
- “WALLET” - reconciliation for the price reduction in buyer’s payment.
You can check the reconciliation sum for an item regardless of the type of reconciliation in the lineItems[].reconciliation.value object.
For a “WALLET” type of reconciliation, we will also return the payment reconciliation amount in the payment.reconciliation object. The seller will receive a payment, the value of which you will check by summing payment.paidAmount.amount and payment.reconciliation.amount.
Sample request:
curl -X GET \
'https://api.allegro.pl/order/checkout-forms/4fceac60-71c6-11eb-bb0e-5f505b61d2dd’ \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Authorization: Bearer {token}'
Click to view sample response:
{
…
"payment": {
"id": "677d4ba1-71c6-11eb-a259-c766517115fd",
"type": "ONLINE",
"provider": "PAYU",
"finishedAt": "2021-03-15T12:18:33.434Z",
"paidAmount": {
"amount": "80", – customer payment amount
"currency": "PLN"
},
"reconciliation": {
"amount": "20", – amount of reconciliation for the price
reduction in buyer’s payment.
Will only occur in the case of
"WALLET" type reconciliation
"currency": "PLN"
}
},
"status": "READY_FOR_PROCESSING",
…
"lineItems": [
{
"id": "ffc36fa0-9584-11e8-8d53-07c966f77738",
"offer": {
"id": "6205584023",
"name": "Lifebelt",
"external": {
"id": "ext_2018_08_17"
}
},
"quantity": 1,
"originalPrice": {
"amount": "80.00",
"currency": "PLN"
},
"price": {
"amount": "80.00",
"currency": "PLN"
},
"reconciliation": {
"value": {
"amount": "20.00",
"currency": "PLN"
},
"quantity": 1,
"type": "WALLET"
},
"selectedAdditionalServices": [ ],
"boughtAt": "2021-03-15T12:18:33.434Z"
}
],
"surcharges": [],
"discounts": [
{
"type": "ALLEGRO_PRICES"
}
],
"summary": {
"totalToPay": {
"amount": "80.00",
"currency": "PLN"
}
},
"updatedAt": "2021-03-15T12:18:33.434Z",
"revision": "dc0f896f"
}
Note! In case of a correct payment (in which there was no overpayment or underpayment), the amount in payment.paidAmount and summary.totalToPay fields should be identical - regardless of whether the order was covered by Allegro Prices.
When in the order we returned the value: “BILLING” in the lineItems[].reconciliation.type field, in response to GET /billing/billing-entries we will return the appropriate billing entry in which the id value in the on billingEntries[].type object will be “PS1” .
Sample responses for different scenarios
Delivery at pickup point:
"delivery": {
"address": { -- customer data
"firstName": "Jan",
"lastName": "Testowy",
"street": "Zielona 90",
"city": "Poznań”,
"zipCode": "62-111",
"countryCode": "PL",
"phoneNumber": "+381 11 1111111"
},
"method": {
"id": "2488f7b7-5d1c-4d65-b85c-4cbcf253fd93", -- shipping method ID
"name": "Allegro Paczkomaty InPost 24/7" -- shipping method name
},
"pickupPoint": { -- informations about
general delivery
"id": “POZ08A”, -- pickup point id
"name": "Paczkomat POZ22A", -- pickup point name
"description": "Stacja paliw BP", -- pickup point description
(if applicable)
"address": { -- pickup point address
"street": "Przybyszewskiego 39A",
"city": "Poznań"
}
},
"cost": {
"amount": "6.00", -- shipping cost
"currency": "PLN"
},
"smart": false
},Cash on delivery:
"payment": {
"id": "2c952542-6967-11e8-b090-8b2d9f391430", -- payment ID
"type": "CASH_ON_DELIVERY" -- payment type
"provider": null,
"finishedAt": "2019-07-23T12:58:58.609Z", -- date on which shipping form
was submitted
"paidAmount": null
},Invoice issued to a company:
"invoice": {
"Required": true, -- values: "TRUE", "FALSE"
(customer doesn't want invoice)
"address": { -- invoice data
"street": "Zielona 90",
"city": "Poznań",
"zipCode": "62-111",
"countryCode": "PL",
"company": {
"name": "Nazwa Firmy Sp. z o.o.", -- company name
"taxId": "525-26-74-798" -- tax ID number
}
}
},Invoices
Add an invoice to the order
You will add an invoice to the order in two steps - first, use POST /order/checkout-forms/{id}/invoices to create invoice object.
Sample request:
curl -X POST \
‘https://api.allegro.pl/order/checkout-forms/a8320af2-5f01-11eb-bbeb-112e13b418c5/invoices' \
-H ‘Accept: application/vnd.allegro.public.v1+json’ \
-H ‘Content-Type: application/vnd.allegro.public.v1+json’ \
-H ‘Authorization: Bearer {token}’ \
-d ‘{
"file": {
“name”: "example-invoice.pdf" - required, file name
},
"invoiceNumber": "FV 01/2020" - not required, invoice number
}’Sample response:
{
"id": "56ae349d-8045-4bb3-adcc-7cf6fb420f61" - invoice id
} Then, use PUT /order/checkout-forms/{id}/invoices/{invoiceId}/file to upload a *.pdf file with invoice. As “invoice.id” pass the id value you received in response to POST method. You can add up to 5 invoices to each order. The file size cannot exceed 3 MB.
Sample request:
curl -X PUT \
‘https://api.allegro.pl/order/checkout-forms/a8320af2-5f01-11eb-bbeb-112e13b418c5/invoices/56ae349d-8045-4bb3-adcc-7cf6fb420f61/file' \
-H ‘Accept: application/vnd.allegro.public.v1+json’ \
-H ‘Content-Type: application/pdf’ \
-H ‘Authorization: Bearer {token}’ \
-d 'data=@example-invoice.pdf’Retrieve information about invoices
Use GET /order/checkout-forms/{id}/invoices to retrieve information about invoices assigned to the order.
Sample request:
curl -X GET \
‘https://api.allegro.pl/order/checkout-forms/a8320af2-5f01-11eb-bbeb-112e13b418c5/invoices' \
-H ‘Accept: application/vnd.allegro.public.v1+json’ \
-H ‘Authorization: Bearer {token}’Sample response:
{
“invoices”: [
{
"id": "56ae349d-8045-4bb3-adcc-7cf6fb420f61", - invoice id
"invoiceNumber": "FV 01/2020", - invoice number
"createdAt": "2021-01-07T15:50:00.000Z", - invoice creation date
"file": {
"name": "example-invoice.pdf", - file name
"uploadedAt": "2021-01-07T15:50:00.000Z", - upload date
"securityVerification": {
"status": "ACCEPTED", - file antivirus verification status,
available values: WAITING, ACCEPTED,
REJECTED
"verifiedAt": "2021-01-07T15:51:00.000Z" - verification date
}
},
"eptVerification": null - value other than null only for
Extended Payment Terms on orders before
17th November 2021
}
]
} How to add tracking number to an item in order
Add tracking number to order
Use POST /order/checkout-forms/{id}/shipments to add tracking number to an order. If you do not pass lineItem.id in your request, we will automatically assign a tracking number to each lineItem.id in your order.
Sample request:
curl -X POST \
https://api.allegro.pl/order/checkout-forms/31896452-2de1-11e9-bced-352ab82ad9cd/shipments \
-H 'Authorization: Bearer {token}' \
-H 'Content-Type: application/vnd.allegro.public.v1+json' \
-H 'Accept: application/vnd.allegro.public.v1+json'
-d '{
"carrierId": "DHL", -- required, you can find available delivery company IDs
via GET /order/carriers in field carriers.id
"waybill": "12345678910PL", -- required, track and trace number
"carrierName": null, -- required, only for “OTHER” value in carrierId field.
Name of the delivery company outside the list.
"lineItems": [ -- not required, list of single purchase events IDs
{
"id": "31896450-2de1-11e9-bced-352ab82ad9cd"
},
{
"id": "5b1f4a62-6969-11e8-b090-8b2d9f391430"
}
]
}Sample response:
{
"waybill": "12345678910PL",
"carrierId": "DHL",
"carrierName": null,
"lineItems": [
{
"id": "31896450-2de1-11e9-bced-352ab82ad9cd"
},
{
"id": "5b1f4a62-6969-11e8-b090-8b2d9f391430"
}
],
"createdAt": "2019-02-18T11:46:48.264Z", -- date of track and trace number
"id": "REhMOjEyMzQ1Njc4OTEwUEw=" -- ID operation of adding a track and trace number
}Retrieving tracking numbers
Use GET /order/checkout-forms/{id}/shipments to to get a list tracking numbers assigned to the order. You can get the CheckoutForm.id from orders resources described here.
Sample request:
curl -X GET \
https://api.allegro.pl/order/checkout-forms/31896452-2de1-11e9-bced-352ab82ad9cd/shipments \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json'Sample response:
{
"shipments": [ -- shipments list
{
"waybill": "12345678910PL", -- track and trace number
"carrierId": "DHL", -- delivery company ID
"lineItems": [ -- list of single purchase events IDs
{
"id": "ed6b4380-3108-11e9-96bc-5f220d078cf7"
}
],
"createdAt": "2019-02-18T12:07:03.353Z", -- date of track and trace number
addition
"id": "REhMOjEyMzQ1Njc4OTEwUEw=" -- track and trace ID
},
{
"waybill": "25825896-32343-55",
"carrierId": "OTHER",
"carrierName": "Kurier_express",
"lineItems": [
{
"id": "ed6b4380-3108-11e9-96bc-5f220d078cf7"
}
],
"createdAt": "2019-02-26T07:13:08.585Z",
"id": "T1RIRVI6MjU4MjU4OTYtMzIzNDNfaW5uYQ=="
}
]
}Customer returns
How to retrieve customer returns list
Using GET /order/customer-returns you will retrieve the list of customer returns available on your account. We will return 100 records by default. You can also retrieve a list tailored to your needs, using parameters:
- limit - specify the number of returns to be returned in the response (takes values from 1 to 1000),
- offset - select the place from which you want to retrieve the next batch of data (takes values from 0 to 1000).
We have also provided filters that will allow you to narrow the obtained results:
- customerReturnId - customer return ID,
- referenceNumber - reference number,
- orderId - order ID,
- items.offerId - offer ID,
- items.name - offer title,
- parcels.waybill - return parcel waybill,
- parcels.carrierId - carrier name,
- parcels.sender.phoneNumber - return parcel sender phone number,
- from - the ID of the last seen customer return,
- createdAt.gte - the earliest return creation date,
- createdAt.lte - the latest return creation date
Sample request:
curl -X GET \
'https://api.allegro.pl/order/customer-returns' \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.beta.v1+json'Click to view sample response:
{
"count": 2, - total number of returns
"customerReturns": [
{
"id": "8228462e-dc5f-4cae-80f6-88b320b2565a", - customer return ID
"createdAt": "2021-07-08T12:13:53.464Z", - customer return creation date
"referenceNumber": "XGQX/2021", - reference number
"orderId": "4a0a6511-dfd7-11eb-b6c4-d37454079c02", - order ID
"items": [ - returned items list
{
"offerId": "7680560740", - offer ID
"quantity": 1, - quantity
"name": "Apple iPhone 12 Pro pacyfic blue 128 GB", - offer title
"price": {
"amount": "1234", - unit price
"currency": "PLN"
},
"url": "https://allegro.pl/oferta/apple-iphone-12-pro-pacyfic-blue-128-gb-7680560740?snapshot=MjAyMS0wNy0wOFQxMDoyOToyNS44O", - offer snapshot
"reason": {
"type": "NOT_AS_DESCRIBED", - return reason
"userComment": "Wrong color" - user comment
}
}
],
"refund": { - data for the return of the payment
"bankAccount": {
"owner": "Adam Adamowski", - owner name
"accountNumber": "90051670524612733466440893", - account number
"iban": "PL90051670524612733466440893", - IBAN
"swift": "ALBPPLPW", - SWIFT code, only for foreign account numbers
"address": { - address
"street": "Grunwaldzka 182",
"city": "Poznań",
"postCode": "60-166",
"countryCode": "PL"
}
}
},
"rejection": null, - return rejection reason
"parcels": [ - return parcel details
{
"createdAt": "2021-07-08T12:13:59.001Z", - parcel creation date
"waybill": null, - waybill numbe
"carrierId": null, - carrier name
"sender": {
"phoneNumber": "+48600600600" - sender phone number
}
}
]
},
{
"id": "4fb9ad4a-a19b-4c08-a6f1-895cb8741258",
"createdAt": "2021-07-08T12:19:47.132Z",
"referenceNumber": "XNLX/2021",
"orderId": "aef2baa1-dfe5-11eb-b6c4-d37454079c02",
"items": [
{
"offerId": "7680560740",
"quantity": 2,
"name": "Apple iPhone 12 Pro pacyfic blue 128 GB",
"price": {
"amount": "11",
"currency": "PLN"
},
"url": "https://allegro.pl/oferta/apple-iphone-12-pro-pacyfic-blue-128-gb-7680560740?snapshot=MjAyMS0wNy0wOFQxMjoxMjoxNS4wMzNaO2J1eW",
"reason": {
"type": "NONE",
"userComment": ""
}
}
],
"refund": {
"bankAccount": {
"owner": "Jan Kowalski",
"accountNumber": "90051670524612733466440893",
"iban": "PL90051670524612733466440893",
"swift": "ALBPPLPW",
"address": {
"street": "Grunwaldzka 182",
"city": "Poznań",
"postCode": "60-166",
"countryCode": "PL"
}
}
},
"rejection": null,
"parcels": [
{
"createdAt": "2021-07-08T12:19:48.838Z",
"waybill": null,
"carrierId": null,
"sender": {
"phoneNumber": "+48777888999"
}
}
]
}
]
}How to retrieve detailed information about customer return
Use GET /order/customer-returns/{customerReturnId} to retrieve detailed information about chosen customer return.
Sample request:
curl -X GET \
'https://api.allegro.pl/order/customer-returns/8228462e-dc5f-4cae-80f6-88b320b2565a' \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.beta.v1+json'Click to view sample response:
{
"id": "8228462e-dc5f-4cae-80f6-88b320b2565a", - customer return ID
"createdAt": "2021-07-08T12:13:53.464Z", - customer return creation date
"referenceNumber": "XGQX/2021", - reference number
"orderId": "4a0a6511-dfd7-11eb-b6c4-d37454079c02", - order ID
"items": [ - returned items list
{
"offerId": "7680560740", - offer ID
"quantity": 1, - quantity
"name": "Apple iPhone 12 Pro pacyfic blue 128 GB", - offer title
"price": {
"amount": "1234", - unit price
"currency": "PLN"
},
"url": "https://allegro.pl/oferta/apple-iphone-12-pro-pacyfic-blue-128-gb-7680560740?snapshot=MjAyMS0wNy0wOFQxMDoyOToyNS44O", - offer snapshot
"reason": {
"type": "NOT_AS_DESCRIBED", - return reason
"userComment": "Wrong color" - user comment
}
}
],
"refund": { - data for the return of the payment
"bankAccount": {
"owner": "Adam Adamowski", - owner name
"accountNumber": "90051670524612733466440893", - account number
"iban": "PL90051670524612733466440893", - IBAN
"swift": "ALBPPLPW", - SWIFT code, only for foreign account numbers
"address": { - address
"street": "Grunwaldzka 182",
"city": "Poznań",
"postCode": "60-166",
"countryCode": "PL"
}
}
},
"rejection": null, - return rejection reason
"parcels": [ - return parcel details
{
"createdAt": "2021-07-08T12:13:59.001Z", - parcel creation date
"waybill": null, - waybill number
"carrierId": null, - carrier name
"sender": {
"phoneNumber": "+48600600600" - sender phone number
}
}
]
}How to reject customer return refund
Use POST /order/customer-returns/{customerReturnId}/rejection to reject customer return refund. In the “reason” field, pass the reason why you are refusing to return.
Sample request:
curl -X POST \
'https://api.allegro.pl/order/customer-returns/8228462e-dc5f-4cae-80f6-88b320b2565a/rejection' \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.beta.v1+json' \
-H 'Content-Type: application/vnd.allegro.beta.v1+json' \
-d '{
"rejection": {
"reason": "Returned item is damaged."
}
}'Click to view sample response:
{
"id": "8228462e-dc5f-4cae-80f6-88b320b2565a", - customer return ID
"createdAt": "2021-07-08T12:13:53.464Z", - customer return creation date
"referenceNumber": "XGQX/2021", - reference number
"orderId": "4a0a6511-dfd7-11eb-b6c4-d37454079c02", - order ID
"items": [ - returned items list
{
"offerId": "7680560740", - offer ID
"quantity": 1, - quantity
"name": "Apple iPhone 12 Pro pacyfic blue 128 GB", - offer title
"price": {
"amount": "1234", - unit price
"currency": "PLN"
},
"url": "https://allegro.pl/oferta/apple-iphone-12-pro-pacyfic-blue-128-gb-7680560740?snapshot=MjAyMS0wNy0wOFQxMDoyOToyNS44O", - offer snapshot
"reason": {
"type": "NOT_AS_DESCRIBED", - return reason
"userComment": "Wrong color" - user comment
}
}
],
"refund": { - data for the return of the payment
"bankAccount": {
"owner": "Adam Adamowski", - owner name
"accountNumber": "90051670524612733466440893", - account number
"iban": "PL90051670524612733466440893", - IBAN
"swift": "ALBPPLPW", - SWIFT code, only for foreign account numbers
"address": { - address
"street": "Grunwaldzka 182",
"city": "Poznań",
"postCode": "60-166",
"countryCode": "PL"
}
}
},
"rejection": {
“reason”: “Returned item is damaged.”, - return rejection reason
“createdAt”: "2021-07-27T11:34:42.499Z" - rejection date
},
"parcels": [ - return parcel details
{
"createdAt": "2021-07-08T12:13:59.001Z", - parcel creation date
"waybill": null, - waybill number
"carrierId": null, - carrier name
"sender": {
"phoneNumber": "+48600600600" - sender phone number
}
}
]
}Payment refunds
How to refund a payment
To initiate a refund of a payment, use POST /payments/refunds.
Note! You need to provide:
buyer’s payment ID (retrieve payment.id using GET order/checkout-forms)
reason for a payment refund
what do you want to refund - you can make a refund for a product, delivery, overpaid, surcharges and additional services.
Optionally, you may also provide a comment in the “sellerComment” field justifying the refund. The buyer will receive this comment in the message confirming the refund request.
If you want to refund a payment for an item, you have two options to choose from. You can provide the selected option as a value in the lineItems.type field:
QUANTITY - refund by number of items. In the “quantity” field, pass the number of items, for which you want to make a refund,
AMOUNT - refund of a specific amount, you can refund a partial price.
Payment refund for item by quantity, for delivery, overpaid, surcharges and additional services:
Click to view sample request:
curl -X POST
‘https://api.allegro.pl/payments/refunds’
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.public.v1+json'
-H 'Content-Type: application/vnd.allegro.public.v1+json'
-d ‘{
"payment": {
"id": "a6bee8b2-8b4e-11e9-8918-07b31163120a" – required, buyer’s payment ID
},
"reason": "REFUND", – required, reason of the
refund, supported values:
REFUND, COMPLAINT,
PRODUCT_NOT_AVAILABLE,
PAID_VALUE_TOO_LOW
"lineItems": [ – not required, list of order
line items, which can be refunded
{
"id": "09f0b4cc-7880-11e9-8f9e-2a86e4085a59", – not required, item id, for
which you want to make payment
refund, you can retrieve lineItem.id
by calling GET order/checkout-forms
"type": "QUANTITY", – type of payment refund for the
product, supported values
QUANTITY (refund by number of items)
or AMOUNT (refund of a specific amount)
“quantity”: 1 – number of items, for which you
want to make a refund
}
],
"delivery": { – not required, payment
refund for delivery
"value": {
"amount": "123.45", – amount, you want to return for
delivery cost
"currency": "PLN"
}
},
"overpaid": { – not required, payment
refund for overpaid
"value": {
"amount": "123.45", – amount, you want to return from
overpaid
"currency": "PLN"
}
},
"surcharges": [ – not required, list of
surcharges for payment, which can
be refunded
{
"id": "09f0b4cc-7880-11e9-8f9e-2a86e4085a59", – required, if you refund surcharge,
you can retrieve surcharge.id by calling
GET /order/checkout-forms
"value": {
"amount": "123.45", – amount, you want to return from
surcharge
"currency": "PLN"
}
}
],
"additionalServices": { – not required, payment
refund for additional services
"value": {
"amount": "123.45", – amount, you want to return for
additional services
"currency": "PLN"
}
}
"sellerComment": "Package returned" – optional commentary to justify refund
}’
Refund of a specific amount for the item:
Click to view sample request:
curl -X POST \
‘https://api.allegro.pl/payments/refunds’ \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Content-Type: application/vnd.allegro.public.v1+json' \
-d ‘{
"payment": {
"id": "a6bee8b2-8b4e-11e9-8918-07b31163120a"
},
"reason": "REFUND",
"lineItems": [
{
"id": "03ec68f0-9d6a-11e9-8f47-458978ef2120",
"type": "AMOUNT",
"value": {
"amount": "100.00",
"currency": "PLN"
}
}
]
}Click to view sample response:
{
"id": "09f0b4cc-7880-11e9-8f9e-2a86e4085a59", -- payment refund id
"payment": {
"id": "a6bee8b2-8b4e-11e9-8918-07b31163120a" -- buyer’s payment id
},
"reason": "REFUND",
"status": "NEW", -- current payment refund status
"createdAt": "2017-05-17T08:36:57.292+02:00", -- payment refund creation datetime
"totalValue": { -- refund amount
"amount": "123.45",
"currency": "PLN"
},
"lineItems": [ -- list of items, for which refund was
made
{
"id": "09f0b4cc-7880-11e9-8f9e-2a86e4085a59",
"type": "QUANTITY",
"quantity": 1,
}
],
"delivery": {
"value": {
"amount": "123.45",
"currency": "PLN"
}
},
"overpaid": {
"value": {
"amount": "123.45",
"currency": "PLN"
}
},
"surcharges": [
{
"id": "09f0b4cc-7880-11e9-8f9e-2a86e4085a59",
"value": {
"amount": "123.45",
"currency": "PLN"
}
}
],
"additionalServices": {
"value": {
"amount": "123.45",
"currency": "PLN"
}
}
}How to retrieve a list of refunded payment
You can retrieve a list of refunded payments by using GET /payments/refunds. By default, you receive list of 50 newest payment refunds.
You can adjust the list to your needs using the following parameters:
limit - define a number of returned operations
offset - define an index of first returned payment operation
e.g. GET /payments/refunds?limit=50&offset=25 will return 50 payment refunds from the defined point.
You can also use filters:
payment refund id - e.g. GET /payments/refunds?id=09f0b4cc-7880-11e9-8f9e-2a86e4085a59
buyer’s payment id - e.g. GET /payments/refunds?payment.id=a6bee8b2-8b4e-11e9-8918-07b31163120a
date of payment refund - you can filter payment refund date using parameters occurredAt.gte (minimum date and time when the refund occurred in ISO 8601 format) and occurredAt.lte (maximum date and time when the refund occurred in ISO 8601 format), e.g. GET/payments/refunds?occurredAt.gte=2019-07-10T11:06:50.935Z&occurredAt.lte=2019-07-15T11:06:50.935Z
status - e.g. GET /payments/refunds?status=”SUCCESS”.
Sample request:
curl -X GET \
‘https://api.allegro.pl/payments/refunds’ \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Content-Type: application/vnd.allegro.public.v1+json' \Click to view sample response:
{
"refunds": [
{
"id": "09f0b4cc-7880-11e9-8f9e-2a86e4085a59", -- payment refund id
"payment": {
"id": "a6bee8b2-8b4e-11e9-8918-07b31163120a" -- buyer’s payment id
},
"reason": "REFUND", -- reason for a payment refund
"status": "SUCCESS", -- current payment refund
status, supported values:
WAITING (we’re trying to take
funds from account),
IN_PROGRESS (we collected
funds from the account and
we have forwarded refund
request to the operator),
SUCCESS (funds returned),
CANCELLED (failed attempt to
collect funds from account
or error on the operator’s
side), PARTIAL (applies
to returns to two operators,
e.g. refund for the item
purchased by PAYU
has been successfully
completed, but refund for
surcharge via P24 has been
failed)
"createdAt": "2017-05-17T08:36:57.292+02:00", -- date and time when the
refund was created
"totalValue": { -- total amount for payment
refund
"amount": "123.45",
"currency": "PLN"
},
"lineItems": [ -- list of line items for
which payment refund was made
{
"id": "09f0b4cc-7880-11e9-8f9e-2a86e4085a59",
"type": "QUANTITY",
"quantity": 5,
"value": null
}
],
"delivery": { -- payment refund for delivery
"value": {
"amount": "123.45",
"currency": "PLN"
}
},
"overpaid": { -- payment refund for overpaid
"value": {
"amount": "123.45",
"currency": "PLN"
}
},
"surcharges": [ -- payment refund for
surcharges
{
"id": "09f0b4cc-7880-11e9-8f9e-2a86e4085a59", -- surcharge id
"value": {
"amount": "123.45",
"currency": "PLN"
}
}
],
"additionalServices": { -- payment refund for
additional services
"value": {
"amount": "123.45",
"currency": "PLN"
}
}
}
],
"count": 50, -- displayed results
"totalCount": 123 -- total count of completed
payment refunds
}Sale commission refunds
How to create a sale commission refund application
You can create a sale commission refund application via POST /order/refund-claims.
Via REST API you can create a sale commission refund application for commissions collected in the last 45 days.
In the request, provide required fields:
lineItem.id - item id, for which you want to receive a sale commission refund. You can retrieve it via GET /order/checkout-forms/{checkoutFormId},
quantity - number of items, for which you want to receive sale commission refund.
Note! For each lineItem.id you can create only one sale commission refund application. Make sure you provide a valid number of items in the quantity field.
Sample request:
curl -X POST
https://api.allegro.pl/order/refund-claims
-H 'Authorization: Bearer {token}'
-H 'Content-Type: application/vnd.allegro.public.v1+json'
-H 'Accept: application/vnd.allegro.public.v1+json'
-d '
{
"lineItem": {
"id": "15f8e350-5252-11ea-875e-a14b8f6a3728"
},
"quantity": 1
}’Sample response:
{
"id": "c5ed3e8c-b37b-4379-892b-4e9bbd8de416" -- sale commission refund
application id. For more details,
e.g. current status, provide this id
as claimId in
GET /order/refund-claims/{claimId}.
}How to retrieve list of sale commission refunds
Via GET /order/refund-claims you can retrieve a list of sale commission refunds. By default, you receive a list of 25 newest refunds applications, the first result is the latest. You can adjust the list to your needs using the following parameters:
limit - define a number of sale commission refunds applications in the response. The maximum value is 100.
offset - define an index of the first returned sale commission refund application.
You can also use filters:
offer identifier - e.g. GET order/refund-claims?lineItem.offer.id=6206823161 will return refunds applications, which are related with offer 6206823161,
buyer login - e.g. GET order/refund-claims?buyer.login=example_login will return refunds applications, which relate to provided buyer,
claim status - e.g. GET order/refund-claims?status=REJECTED will return rejected refunds applications. List of values can be found in our documentation.
Sample request:
curl -X GET
https://api.allegro.pl/order/refund-claims
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.public.v1+json'Click to view sample response:
{
"refundClaims": [
{
"id": "c5ed3e8c-b37b-4379-892b-4e9bbd8de416", -- sale commission refund
application id
"status": "REJECTED", -- current refund application
status
"quantity": 1, -- number of items, for
which for which you want to
receive sale commission refund
"commission": {
"amount": 0.60, -- commission amount of
sales
"currency": "PLN"
},
"buyer": {
"id": "441827210",
"login": "example login"
},
"createdAt": "2020-03-02T14:27:20.560Z", -- date the refund application
was created
"type": "MANUAL", -- type of application, available
values: MANUAL (application was
created manually by the seller),
AUTOMATIC (application was created
automatically).
"lineItem": {
"id": "2035a9e0-3c66-11ea-9902-0b71080f41e0", -- item id, for which you want
to receive a commission
refund
"quantity": 3, -- number of items in order
"boughtAt": "2020-01-21T15:53:17.829Z", -- date of purchase
"offer": {
"id": "6216558337",
"name": "test offer"
}
}
},
{
"id": "17f69337-a5bc-44d1-bc5d-4ad2a6b9ce0d",
"status": "GRANTED",
"quantity": 1,
"commission": {
"amount": 0.05,
"currency": "PLN"
},
"buyer": {
"id": "441827210",
"login": "example_login"
},
"createdAt": "2020-03-02T13:20:27.523Z",
"type": "MANUAL",
"lineItem": {
"id": "ad727280-5961-11ea-9e7e-ef3e4a9eb4c3",
"quantity": 1,
"boughtAt": "2020-02-27T13:04:31.952Z",
"offer": {
"id": "6206857553",
"name": "test offer"
}
}
}
],
"count": 2 -- summary number of
sale commission refunds
applications
}How to retrieve single sale commission refund
Via GET /order/refund-claims/{claimId} you can retrieve details for a single refund application, that you provided in the request.
Sample request:
curl -X GET
https://api.allegro.pl/order/refund-claims/17f69337-a5bc-44d1-bc5d-4ad2a6b9ce0d
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.public.v1+json'Sample response:
{
"id": "17f69337-a5bc-44d1-bc5d-4ad2a6b9ce0d",
"status": "GRANTED",
"quantity": 1,
"commission": {
"amount": 0.05,
"currency": "PLN"
},
"buyer": {
"id": "441827210",
"login": "testowy_login"
},
"createdAt": "2020-03-02T13:20:27.523Z",
"type": "MANUAL",
"lineItem": {
"id": "ad727280-5961-11ea-9e7e-ef3e4a9eb4c3",
"quantity": 1,
"boughtAt": "2020-02-27T13:04:31.952Z",
"offer": {
"id": "6206857553",
"name": "oferta testowa"
}
}
}How to cancel sale commission refund
Via DELETE /order/refund-claims/{claimId} you can cancel the sale commission refund that you provided in the request. You can cancel refunds applications only in statuses IN_PROGRESS and APPEALED, in other cases, we will return error 422.
Sandbox
To take full advantage of the described resources in a test environment (Allegro Sandbox):
Register two accounts:
a business account (on which you will list your items for sale) - fill in the address details and activate the account,
a standard account (from which you will make purchases as a customer) - fill in the address details and activate the account,
Verify your business account.
List an offer on Sandbox from the seller’s account - you can do this via sell form or API.
Log in to the buyer’s account and go to the page of the selected offer:
add the item to the cart or use Buy Now,
fill in the delivery address, select the delivery and payment method,
click Buy and pay (a payment simulator is available on the Sandbox, i.e. you do not have to make a real payment).
As a seller, you can check the received orders in the Orders tab or through API.
You can find basic information about the test environment in our tutorial.
FAQ
I received only one event - READY_FOR_PROCESSING in the response for GET /order/events. Is this a bug?
No, you shouldn’t treat it as a bug. There must be at least one event for each order.
I received two different READY_FOR_PROCESSING events, but they apply to the same payment. Is this situation normal?
Yes, you can retrieve several events of the same type, in that situation you should check the order id in the checkoutForm object.
Can events occur in an unexpected order, e.g. I will receive FILLED_IN before BOUGHT?
Yes, you can receive events in random order.
I received FILLED_IN event in the event journal with a specific order id. When I try to provide this id via GET /order/checkout-forms/{id} I get status 404 in the response with the information that order was not found. What happened with this order?
In this case, the buyer made separate purchases and then combine them into one payment. You will receive a new event with new checkoutForm.id, previous checkoutForm.id will not be available anymore. To identify this situation you can rely on lineItem.id (if one lineItem.id appears in several orders, it means that buyer combined his purchases).
I received READY_FOR_PROCESSING event, so I start processing order. How can I verify that the buyer doesn’t meanwhile cancel the order?
When you changing the order fulfillment status via PUT /order/checkout-forms/{id}/fulfillment, use an optional parameter - checkoutForm.revision. You can retrieve it in the response for:
In this field, we inform about order revision. Owing to it you will be sure that you are changing the order fulfillment status (“fulfillment.status”), which exactly the same copy is in Allegro.w Allegro.
In this field, we inform about order revision. Owing to it you will be sure that you are changing the order fulfillment status (“fulfillment.status”), which exactly the same copy is in Allegro.
If I add tracking number via POST /order/checkout-forms/{id}/shipments will the order fulfillment status automatically change to SENT?
Order fulfillment status will automatically change to SENT only if the seller has a subscription enabled and select this option in settings in the Orders tab. In other cases, you need to do this manually via PUT /order/checkout-forms/{id}/fulfillment.
Can there be two different orders with the same checkout-form.id?
Checkout-form.id is unique. There won’t be two different orders with the same id.
How can I filter orders by assigned tracking numbers?
Use the fulfillment.shipmentSummary.lineItemsSent parameter in this case. You will find information on whether ordered items have a tracking number. Available values specify assigned tracking numbers to:
ALL - all items in the order,
SOME - at least one item in the order. Via GET /order/checkout-forms/{id}/shipments you can check items with added a number.
NONE - none item in the order.
e.g. GET /order/checkout-forms?fulfillment.shipmentSummary.lineItemsSent=ALL - will return orders with a tracking number added to all items.
List of resources
You will find full documentation of resources in the swagger.yaml form file here.
List of basic resources used in tutorial:
- GET /order/events - retrieve a list of events
- GET /order/event-stats - retrieve information about the last event
- GET /order/checkout-forms/{id} - retrieve order details
- PUT /order/checkout-forms/{id}/fulfillment - change order fulfillment status
- POST /order/checkout-forms/{id}/shipments - add a track and trace number to selected order
- GET /order/customer-returns/{customerReturnId} - retrieve detailed information about customer return
- POST /order/customer-returns/{customerReturnId}/rejection - reject customer return refund
- POST /payments/refunds - initiate a refund of a payment
- POST /order/refund-claims - create a sale commission refund application
List of supporting resources used in tutorial:
- GET /order/checkout-forms - retrieve an order list
- GET /order/carriers - retrieve carrier list
- GET /order/checkout-forms/{id}/shipments - retrieve a list of tracking numbers assigned to the order
- GET /order/customer-returns - retrieve a list of customer returns
- GET /payments/refunds - retrieve a list of refunded payment
- GET /order/refund-claims - retrieve list of sale commission refunds
- GET /order/refund-claims/{claimId} - retrieve single sale commission refund
- DELETE /order/refund-claims/{claimId} - cancel sale commission refund