How to process orders
How to process orders in Allegro REST API
Orders in Allegro REST API
Processing orders in Allegro REST API
There are two ways:
- monitor the event log,
- search the order list.
Events have statuses that indicate the order stage. There are three types of statuses you can check in the type field:- BOUGHT - a customer made the purchase but did not pay for the order;
- FILLED_IN - this status 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.
Event log
Call GET on /order/events to retrieve events for monitoring customer activities such as:
- purchase,
- filling in shipping form,
- payment cancellation,
- making a surcharge.
- there can be several activities concerning one order (at least one) e.g. purchase, payment and surcharge;
- order and number of created events will not change;
- list of events is ordered by time of occurrence – to establish duplicates and timeline pay attention to the occurredAt field;
- in some cases the events can occur in an unexpected order; in other word a READY_FOR_PROCESSING event may occur before FILLED_IN one and it is not an error.
How to find the newest event
Use the GET method on the /order/event-stats resource, you can retrieve information about the last event of the authorized seller. With this data, you will be able to read subsequent events, starting from the received identifier within this resource. All you have to do is pass the id of the last event by calling the method GET on resource /order/events. For bottom example it will be GET /order/events?from=1532603898317497.
Przykładowy request
curl -X GET \
'https://api.allegro.pl/order/event-stats' \
-H 'authorization: Bearer {token}' \
-H 'accept: application/vnd.allegro.beta.v1+json'{
"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 call GET on /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:
'https://api.allegro.pl/order/events’
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.beta.v1+json'
- retrieve 500 historical 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
{
"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"
}
},
"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"
}
},
"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"
}
},
"type": "READY_FOR_PROCESSING",
"occurredAt": "2018-07-03T08:31:34.731Z"
}
]
}Order list
We have introduced an order list you can retrieve by calling GET on /order/checkout-forms.
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:
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, e.g. https://api.allegro.pl/order/checkout-forms?status=BOUGHT
You can also get order list from indicated period of time, 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 Sample request:
- 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, e.g. https://api.allegro.pl/order/checkout-forms?status=BOUGHT
You can also get order list from indicated period of time, 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 Sample request:
'https://api.allegro.pl/order/checkout-forms’
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.beta.v1+json'
{
"checkoutForms": [
{
"id": "000f8281-841b-11e8-ac45-09db60ede9d6", -- order id
"messageToSeller": "message", -- message from customer
"buyer": {
"id": "54031508", -- customer id
"email": "example@mail.pl", -- customer e-mail
"login": "example_login", -- customer login
"guest": false, -- two values are supported
-- false (logged-on customer)
and true (guest)
"phoneNumber": "+48 000 966 528" -- phone number from customer
settings
},
},
"payment": { -- informations about payment
"id": "abd30d72-9583-11e8-96ed-27298c74ae02",-- payment id
"type": "ONLINE", -- payment type, two values
are supported: “ONLINE” or
“CASH_ON_DELIVERY"
"provider": "PAYU" -- payment orovider “PAYU”
or “P24”
},
"status": "FILLED_IN", -- payment status
"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)
},
"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"
},
"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": "253.41", -- summary price
"currency": "PLN"
}
}
},
{
"id": "39f6cc51-9583-11e8-8d53-07c966f77738",
"buyer": {
"id": "43544044",
"email": "example1@mail.pl",
"login": "example_login1",
"guest": false,
"phoneNumber": "+48 000 966 528" -- phone number from customer
settings
},
"status": "BOUGHT",
"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"
},
"boughtAt": "2018-08-01T12:05:53.027Z"
}
],
"surcharges": [],
"discounts": [],
"summary": {
"totalToPay": {
"amount": "3300.00",
"currency": "PLN"
}
}
},
{
"id": "4db701f0-7e9b-11e8-a346-0ff9a46a7007",
"buyer": {
"id": "43955752",
"email": "example2@mail.pl",
"login": "example_login2",
"guest": false.
"phoneNumber": "+48 000 966 528"
},
"payment": {
"id": "abd30d72-9583-11e8-96ed-27298c74ae02", -- payment id
"type": "ONLINE", -- payment type, two values
are supported: “ONLINE” or
“CASH_ON_DELIVERY"
"finishedAt": "2018-07-03T08:31:34.731Z", -- payment date
"paidAmount": { -- value in payment
"amount": "4351.60",
"currency": "PLN"
}
},
"status": "READY_FOR_PROCESSING",
"delivery": { -- delivery address
"address": {
"firstName": "Jarek",
"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
},
"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"
},
"boughtAt": "2018-07-03T08:31:15.615Z"
}
],
"surcharges": [],
"discounts": [],
"summary": {
"totalToPay": {
"amount": "4351.60",
"currency": "PLN"
}
}
}
],
"count": 3, -- number of orders in this response
"totalCount": 3 -- summary number of orders for seller
}Retrieving order details
Call GET on /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.
'https://api.allegro.pl/order/checkout-forms/{checkoutForm_id}’
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.beta.v1+json'
{
"id": "760c0fa1-6d85-11e8-beae-39b3e51dda59", -- order id
"buyer": {
"id": "54031508", -- customer id
"email": "example@mail.pl", -- customer’s email address
"login": "example_login", -- customer login
"guest": false -- two values are supported
- false (logged-on customer)
and true (guest)
},
"payment": {
"id": "7ba94950-6d85-11e8-9fe4-e9ed44ab58af",-- payment ID
"type": "CASH_ON_DELIVERY" -- payment type “ONLINE” or
“CASH_ON_DELIVERY"
},
"status": "READY_FOR_PROCESSING",
"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)
},
"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": 1,
"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
{
"name": "Zapakuj na prezent", -- service name
"price": {
"amount": “20.00”, -- service cost
"currency": "PLN"
},
"quantity": 1 -- 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": “152.00”, -- total payment amount (including
discount and cost of additional
services and shipping)
"currency": "PLN"
}
}
}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.
Eliminating overpayment and underpayment:
Eliminating overpayment and underpayment:
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
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”
}
],
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
"price": {
"amount": “12.00”, -- surcharge amount
"currency": "PLN"
}
}
],
Sample responses for different scenarios:
General delivery
Cash on delivery
Invoice issued to a company
"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
},
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
}
}
},Shipments
How to add tracking number to order
Use POST on /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:
Sample response:
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.beta.v1+json' \
-H 'Accept: application/vnd.allegro.beta.v1+json'
-d '{
"carrierId": "DHL", -- required, delivery company ID, available values:
“UPS”, “INPOST", "DHL", "GLS", "RUCH", "POCZTA_POLSKA",
"DPD", "POCZTEX", "FEDEX", "TNT_EXPRESS",
"DB_SCHENKER", "RABEN", "GEIS", "DTS", "PEKAES",
"PATRON", X_PRESS_COURIERS, RHENUS_LOGISTICS, "OTHER”.
"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 a list of tracking numbers
Use GET on /order/checkout-forms/{checkoutForm.id}/shipments to get a list tracking numbers assigned to the order. You can get the CheckoutForm.id from orders resources described here.
Sample request:
Sample request:
curl -X GET \
https://api.allegro.pl/order/checkout-forms/31896452-2de1-11e9-bced-352ab82ad9cd/shipments \
-H 'Authorization: Bearer {token}' \
-H 'Content-Type: application/vnd.allegro.beta.v1+json' \
-H 'Accept: application/vnd.allegro.beta.v1+json'
{
"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=="
}
]
}Changelog
How to process orders in Allegro REST API
Point 7
2019-02-27 New resource to get a track and trace number from order [BETA]
Point 7
2019-02-19 New resource to add a track and trace number in order [BETA]
All
2018-11-26 New “external” field available in events and orders
Point 4
2018-10-25 New “discounts” field available in order details
Point 2
2018-08-16 A new resource that you will retrieve the id of the last event
Version
2018-08-07 New resources for order management i beta version