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.
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"
"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
},
"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”) 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.
Note! Until the beginning of 2021, you can disable the option to cancel the order for all your orders. You can do it on Orders settings website.
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"
}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"
}
}
],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
}
}
},How to add tracking number to an item in order
Add tracking number to order
Use POST /order/checkout-forms/{checkoutForm.id}/shipments to add a track and trace number to selected single purchase events (lineItem.Id) in an order. You can get the CheckoutForm.id and lineItem.id from orders resources described here.
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": [ -- 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/{checkoutForm.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=="
}
]
}Payment refunds
How to refund a payment
To initiate a refund of a payment, use POST /payments/refunds.
You can refund payments created after 31 July, 2019.
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.
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"
}
}
}’
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
"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",
"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",
"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.
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
- 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 /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