How to process orders
How to process orders in Allegro REST API
Orders in Allegro REST API
Processing orders in Allegro REST API
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. For example, You can retrieve several events READY_FOR_PROCESSING, therefore you should the logic of your order processing on checkoutForm object;
- you can retrieve events from last 60 days;
- order and number of created events will not change;
- list of events is ordered by time of occurrence - from oldest to newest - to establish duplicates and timeline pay attention to the 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 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.public.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.public.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"
}
]
}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.public.v1+json'
{
"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” or
“CASH_ON_DELIVERY"
"provider": null,
"finishedAt": "2019-07-23T12:58:58.609Z", -- date on which shipping form
was submitted
"paidAmount": null
},
"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)
"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": 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"
}
}
}Order list
You can retrieve an order list by calling GET on /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, e.g. https://api.allegro.pl/order/checkout-forms?status=BOUGHT
- 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
- Period of timein 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
Sample request:
curl -X GET \
'https://api.allegro.pl/order/checkout-forms’
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.public.v1+json'
{
"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, 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)
"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"
},
"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": "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",
"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": "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, 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": "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"
},
"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
}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
"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
}
}
},Shipments
How to add tracking number to an item in 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.public.v1+json' \
-H 'Accept: application/vnd.allegro.public.v1+json'
-d '{
"carrierId": "DHL", -- required, delivery company ID, available values:
“UPS”, “INPOST", "DHL", "GLS", "RUCH", "POCZTA_POLSKA",
"DPD", "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 'Accept: application/vnd.allegro.public.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=="
}
]
}Payment refunds
How to refund a payment
To initiate a refund of a payment, use POST /payments/refunds resource.
Note! You need to provide :
Sample request - payment refund for item by quantity, for delivery, overpaid, surcharges and additional services:
You can refund payments created after 31 July, 2019.
- buyer’s payment ID (retrieve payment.id by calling 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.
Sample request - payment refund for item by quantity, for delivery, overpaid, surcharges and additional services:
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"
}
}
}’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"
}
}
]
}{
"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:
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.
- 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”.
You can also use filters:
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' \
{
"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
}Changelog
How to process orders in Allegro REST API
All
2019-10-09 New field “calculatedNumberOfPackages” in orders
Version
2019-10-07 Resources for adding tracking number to order in public version
Version
2019-09-13 Resources for order management in public version
Point 8
2019-08-01 New resources for payment refunds
Point 3
2019-07-25 New feature - "payment.FinishedAt" available in cash on delivery orders
Point 3
2019-06-28 New feature to filtering by payment.id and surcharges.id
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