curl --request GET \
--url https://api.listo.delivery/v1/deliveries/{id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.listo.delivery/v1/deliveries/{id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.listo.delivery/v1/deliveries/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.listo.delivery/v1/deliveries/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.listo.delivery/v1/deliveries/{id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.listo.delivery/v1/deliveries/{id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.listo.delivery/v1/deliveries/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"id": "dlv_7hK2mQ9xR4tV6bN1cZ8sLwYe",
"external_id": "order-card",
"code": "LS-2001",
"status": "awaiting_payment",
"store_id": "st_4bR8kM2wQ7xT1nV5cZ9pLdYe",
"test": false,
"payment": {
"method": "card",
"status": "awaiting_payment",
"url": "https://app.listo.delivery/p/abc123",
"cash_to_collect_cents": null,
"paid_at": null
},
"order_value_cents": 3630,
"fee_cents": 1200,
"business_fee_cents": 0,
"customer_fee_cents": 1200,
"currency": "MXN",
"quote_id": "qt_5nW3jP8vT2xQ6bM9cZ1sRdKe",
"pickup": {
"name": "Tortería La Mera Mera",
"street": "Av. Juan Palomar y Arias 765",
"lat": 20.691145,
"lng": -103.426885,
"notes": "Toca el timbre del local, no la puerta principal"
},
"dropoff": {
"name": "Ana Torres",
"phone": "+528112345678",
"street": "Blvd. Puerta de Hierro 4965",
"apt_unit": "Apt 3",
"lat": 20.709395,
"lng": -103.413393,
"notes": "Ring buzzer 3",
"handoff": "meet_at_door"
},
"manifest": null,
"courier": null,
"pickup_eta_at": null,
"dropoff_eta_at": null,
"tracking_url": null,
"verification": null,
"proof": null,
"cancellation": null,
"failure_reason": null,
"support_reference": null,
"pickup_ready_at": null,
"requested_at": null,
"courier_assigned_at": null,
"picked_up_at": null,
"delivered_at": null,
"canceled_at": null,
"returned_at": null,
"created_at": "2026-07-31T22:14:45Z",
"updated_at": "2026-07-31T22:14:45Z",
"charges": [],
"tip_cents": 0,
"origin": "api",
"refunds": [],
"refunded_cents": 0,
"refundable_cents": 0,
"vehicle": "moto",
"return_verification": {
"pincode": null
},
"proofs": {
"pickup": null,
"dropoff": null,
"return": null
}
}{
"error": {
"code": "not_found",
"message": "No resource with that id exists for this API key.",
"param": null,
"retryable": false,
"doc_url": "https://docs.listo.delivery/en/errors/not_found",
"request_id": "0b1f6c9a-7e2d-4c53-9a41-5d8e3f2a6b10"
}
}Fetch a delivery
Fetches one delivery by its dlv_ id.
charges carries what a trip that was driven but wasted was billed
at: the delivery fee for each leg driven, less your own store markup.
It is empty on almost every delivery. Each entry’s
type is one of exactly two values, and they are the ones to branch on
when you bill it back to your own merchant:
cancellation_fee, for a cancellation late enough that a courier was already working on the order. One leg, so one delivery fee.return_fee, for a return trip after a failed dropoff. A return bills as ONE entry covering both legs of the journey, not two, so it is twice what a cancellation on the same order would have been.
amount_cents is positive here, because it states what you were
charged. The same movement on GET /v1/ledger is a signed row, so it
reads negative there.
This amount changed on 2026-08-29. It used to be what the wasted trip cost Listo; it is now the delivery fee for the legs that were driven, which is a larger number on the same orders. Nothing about the shape of this field moved, so anything that reads the amount rather than assuming it keeps working unchanged.
A charge can arrive on the delivery’s final delivery.status_changed
event or, when the cost settles afterwards, on a later
delivery.updated. You cannot assume which, so read charges on both:
billing the moment a delivery reaches its terminal status bills short
on every order whose cost landed late.
curl --request GET \
--url https://api.listo.delivery/v1/deliveries/{id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.listo.delivery/v1/deliveries/{id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.listo.delivery/v1/deliveries/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.listo.delivery/v1/deliveries/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.listo.delivery/v1/deliveries/{id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.listo.delivery/v1/deliveries/{id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.listo.delivery/v1/deliveries/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"id": "dlv_7hK2mQ9xR4tV6bN1cZ8sLwYe",
"external_id": "order-card",
"code": "LS-2001",
"status": "awaiting_payment",
"store_id": "st_4bR8kM2wQ7xT1nV5cZ9pLdYe",
"test": false,
"payment": {
"method": "card",
"status": "awaiting_payment",
"url": "https://app.listo.delivery/p/abc123",
"cash_to_collect_cents": null,
"paid_at": null
},
"order_value_cents": 3630,
"fee_cents": 1200,
"business_fee_cents": 0,
"customer_fee_cents": 1200,
"currency": "MXN",
"quote_id": "qt_5nW3jP8vT2xQ6bM9cZ1sRdKe",
"pickup": {
"name": "Tortería La Mera Mera",
"street": "Av. Juan Palomar y Arias 765",
"lat": 20.691145,
"lng": -103.426885,
"notes": "Toca el timbre del local, no la puerta principal"
},
"dropoff": {
"name": "Ana Torres",
"phone": "+528112345678",
"street": "Blvd. Puerta de Hierro 4965",
"apt_unit": "Apt 3",
"lat": 20.709395,
"lng": -103.413393,
"notes": "Ring buzzer 3",
"handoff": "meet_at_door"
},
"manifest": null,
"courier": null,
"pickup_eta_at": null,
"dropoff_eta_at": null,
"tracking_url": null,
"verification": null,
"proof": null,
"cancellation": null,
"failure_reason": null,
"support_reference": null,
"pickup_ready_at": null,
"requested_at": null,
"courier_assigned_at": null,
"picked_up_at": null,
"delivered_at": null,
"canceled_at": null,
"returned_at": null,
"created_at": "2026-07-31T22:14:45Z",
"updated_at": "2026-07-31T22:14:45Z",
"charges": [],
"tip_cents": 0,
"origin": "api",
"refunds": [],
"refunded_cents": 0,
"refundable_cents": 0,
"vehicle": "moto",
"return_verification": {
"pincode": null
},
"proofs": {
"pickup": null,
"dropoff": null,
"return": null
}
}{
"error": {
"code": "not_found",
"message": "No resource with that id exists for this API key.",
"param": null,
"retryable": false,
"doc_url": "https://docs.listo.delivery/en/errors/not_found",
"request_id": "0b1f6c9a-7e2d-4c53-9a41-5d8e3f2a6b10"
}
}Authorizations
Your API key, sent as Authorization: Bearer <key>. Live and test keys are separate; the key you send decides which world the call acts in. To try calls, use a test key (it starts with lst_test_): no real courier is sent and no real money moves, but webhooks fire and the dropoff.phone you give can receive WhatsApp messages, so use your own number. A live key (it starts with lst_live_) books and charges real deliveries.
Path Parameters
Response
The request succeeded.
The shape of a delivery: every field the object can carry, with the
nullability each one really has. It is the response of every operation
that answers a delivery (the create, the fetch, a list row, the
reschedule, the cancel, the retry and the refund) and the data of
every full delivery event, so ONE type holds all of them.
Every operation returns the whole object. A field that a given call
cannot yet have is present and null rather than missing: a create
response has a null courier, because no courier has been assigned
yet, and a reschedule only ever answers with a still-scheduled order,
so its delivered_at is null.
Money is integer centavos, timestamps are ISO-8601 in UTC, and every enum below is ours rather than a passthrough of anyone else's.
The delivery id, dlv_ prefixed.
"dlv_7hK2mQ9xR4tV6bN1cZ8sLwYe"
Your own order reference, echoed back exactly as you sent it.
"order-841"
Which lane created the delivery. api is one you created through
POST /v1/deliveries. console is one the store dispatched itself
from the Listo merchant console, which a store can do only at the
full access tier. whatsapp is one a customer ordered from the
store in a chat, which the store then accepted; no operator typed
it anywhere.
Always present, never null, and fixed for the life of the delivery.
A console order carries a null external_id, but read this field
rather than that null: the missing reference is a consequence of the
lane, not a way of identifying it.
api, console, whatsapp "api"
The human order code the courier and our support quote. Unique per store, not globally, so never address an order by it.
"LS-2048"
delivered, returned and canceled are terminal. no_courier is
a dead end you can retry or cancel. A returned delivery is this
same object throughout; there is no second delivery for the return
leg.
returning: the drop-off failed and the courier is bringing the
order back to the store; it ends in returned. It is NOT terminal,
and it is where a failed delivery now spends the minutes between the
courier giving up at the customer's door and the order actually
arriving back. returned means the order is back. Treat returning
as a live delivery: the courier is still moving and
delivery.courier_location events keep arriving for it.
The return charge is posted when the delivery enters returning,
not when it reaches returned, so charges is already complete on
the returning event.
awaiting_location: an order the store took through Listo's console
or its WhatsApp assistant, held for the drop-off location. No
courier is requested yet. The customer confirms the location on a
map link or by sharing it in the WhatsApp chat, or the store
confirms it from its console. The delivery then moves to
scheduled or dispatching; to no_courier when a courier
cannot be requested for it (the location is outside where the
store delivers, or the store itself cannot request a courier right
now); or to canceled if the order is canceled or the store
changes it to a pickup at the counter. A delivery you create
through this API never sits in it.
awaiting_payment, awaiting_location, scheduled, dispatching, courier_assigned, picking_up, en_route, returning, delivered, returned, canceled, no_courier The st_ id of the store the courier collects from.
Whether this order lives in the sandbox. Derived from the store, so there is no field to set: a test key can only reach test stores.
How the customer pays, and where that got to.
Show child attributes
Show child attributes
The goods value you sent, untouched.
The total delivery fee.
The part of fee_cents charged to you.
The part of fee_cents charged to the customer. Always sums with
business_fee_cents back to fee_cents.
The courier tip you sent on this delivery, paid to the courier and
passed on at cost with no margin taken. Deliberately OUTSIDE
fee_cents, which is the delivery fee business_fee_cents and
customer_fee_cents sum back to. 0 when you sent none, and never
null.
MXN The qt_ quote this order bound, so you can tie the price you were
quoted to the order that spent it. Null when the order was priced
inline instead.
Where the courier collects, snapshotted at create, so a historical order keeps reporting where the courier actually went even after the store is renamed or moved.
Show child attributes
Show child attributes
Where the courier delivers, echoed back as you sent it.
Show child attributes
Show child attributes
The descriptive item list you sent, for the courier. Money never
comes from it, with one exception: an item sized xlarge makes the
trip a car. Null when you sent none.
Show child attributes
Show child attributes
What the trip was priced and dispatched as: car when you asked for
one or when an item was sized xlarge, moto otherwise. A car's
surcharge is inside fee_cents. Always present, never null, and
fixed for the life of the delivery.
Not the vehicle that arrived. That is courier.vehicle_type, which
can be a car on a moto trip without the fee changing.
moto, car "moto"
Null until a courier is assigned, and then FROZEN: a terminal delivery keeps reporting who carried it.
Show child attributes
Show child attributes
When the courier is expected at the store. Absolute, so you compute your own countdown; a countdown computed here is stale before you read it.
When the courier is expected at the customer. Null until there is
an estimate, and null again once the drop-off has failed
(returning, returned): the courier is then bringing the order
back to the store, there is no arrival at the customer left to
describe, and the time it gets back to the store is never published
here.
The branded live tracking page for the customer: the map, the courier, the delivery code and what is owed at the door. Null when there is no page to point at, so you never relay a dead link.
There is a page from the moment the order is dispatched, including the whole window before a courier is assigned, and for 48 hours after the order is delivered, canceled or returned. It is null while an order is still held awaiting payment or awaiting a confirmed drop-off pin, and null again once that 48 hours has passed.
"https://app.listo.delivery/t/abc123"
Present only when the order carries a dropoff PIN: when you asked
for one (verification.dropoff_pincode on the create), or when
Listo requires a PIN on every delivery of this store's account, in
which case it is present even though you did not ask. pincode is
null until the order is actually dispatched, which is when the code
is minted.
Show child attributes
Show child attributes
The return code (código de devolución). When an order cannot be
delivered and the courier brings it back to the store, the courier
must be given this code at the store to hand the order over; without
it the return cannot be completed. pincode is a 4-digit string
while the delivery is returning, and null in every other state
(before the return, and once it is returned). The object is
always present, so this field never needs a presence check. It
arrives in delivery.status_changed (the move into returning) and
in delivery.updated, which carry the whole object. A new attempt
(a retry) gets its own code. Show it to the store, and never to the
customer.
Show child attributes
Show child attributes
Proof of delivery. Null unless we hold some, and each field is null
when that piece is missing; a photo with no signature is normal. The
URLs are Listo's own signed links to the stored copy and are valid
for 24 hours from the response (or webhook) that carried them:
fetch GET /v1/deliveries/{id} again for a fresh link, or keep a
copy. A URL is null until Listo has its own copy of the image
(a few seconds after the courier takes it); the copy's arrival is
announced by a delivery.updated webhook that carries the link.
It may come from a delivery attempt that failed at the
door, so it is not by itself proof that the order was handed over:
proofs.dropoff.delivered says which. Prefer proofs, which keeps
each moment of the trip apart.
Show child attributes
Show child attributes
The evidence the trip left, one entry per moment. Each moment is
null until it happens (nothing has been captured for it yet), so
this object is always present with its three keys. A photo or
signature link is Listo's own signed link to the stored copy, and
it is null until Listo holds that copy (a few seconds after the
courier takes the photo): the rest of the moment, the signer, the
time and the distance, is there from the start, and when the copy
lands a delivery.updated webhook carries the link. Each link is
valid for 24 hours from the response (or webhook) that carried
it: it is a short-lived signed link, never a permanent one. A
partner that needs the image later fetches
GET /v1/deliveries/{id} again for a fresh link, or keeps a copy.
Show child attributes
Show child attributes
Who called the order off, and why. Null on an order that was not cancelled.
Show child attributes
Show child attributes
Why a dispatch failed, bucketed by whose side the problem is on, so
you can act on it rather than just retry blindly.
no_couriers_available is the retriable one.
delivery_failed is the honest catch-all. Null unless a failure was
recorded.
no_couriers_available, address_unreachable, customer_unavailable, delivery_failed, null What a trip that was driven but wasted was billed at: the delivery fee for each leg driven, less your own store markup. Empty on almost every delivery, and never null.
This amount changed on 2026-08-29. It used to be what the wasted trip cost Listo, so expect larger values on the same orders from that date onward. The field itself is unchanged.
Always present on a delivery object, so treat an absent charges
as impossible rather than as "no charges". It is in this schema's
required list for that reason.
A charge can arrive on the delivery's final
delivery.status_changed or, when the cost settles afterwards, on
a later delivery.updated. You cannot assume which, so read this
on both: billing the moment a delivery reaches its terminal status
bills short on every order whose cost landed late.
The same movement appears on GET /v1/ledger as a signed row, so
it reads negative there while amount_cents here is positive.
Show child attributes
Show child attributes
Every time money went back to the customer on this order, newest first. Empty on an order that has never been refunded, and never null.
Always present on a delivery object, so treat an absent refunds
as impossible rather than as "no refunds". It is in this schema's
required list for that reason, exactly as charges above is.
It is a LIST because refunds repeat: a partial refund is followed
by another refund, each with its own amount, its own reason and its
own outcome. Every refund we can see is here whoever made it, which
is what makes the list worth reconciling against. The connected
account belongs to the merchant of record, which can refund a charge
on it without going through us at all; those arrive as
requested_via: external, and a list that showed only the refunds
you asked for would silently disagree with this order's own
payment.status.
A refund rides delivery.updated, never an event of its own.
Show child attributes
Show child attributes
The sum of the SUCCEEDED refunds above, in Mexican peso cents. 0,
never null, on an order nothing has gone back on. A pending refund
is not counted, because the money has not moved and may yet be
refused.
Published rather than left for you to compute, because the array
cannot always be summed correctly: a refund of the remaining balance
carries no amount_cents until it is confirmed, so adding the
list up counts it as zero and reads the whole charge as still
refundable. We take that case pessimistically instead, as having
taken the entire remaining balance, because guessing low ends in
refunding a customer twice.
What a further refund could still return: what the customer paid
(order_value_cents plus customer_fee_cents, which IS the charge)
minus refunded_cents, floored at zero. 0, never null.
0 on any order with no collected card payment behind it, whatever its value. Cash never touched our rails, a prepaid order's customer is yours and we hold nothing of theirs, and an order still awaiting payment was never charged, so there is nothing on any of them a refund could return.
This is the ceiling POST /v1/deliveries/{id}/refunds refuses an
amount_cents against, so read it before you call rather than
discovering the bound from a refund_amount_too_large.
A short handle to quote when you escalate an order to us. Null until the order reaches dispatch.
"2080F"
The scheduled pickup time you asked for. Null on a dispatch-now order.
When a courier was first observed on the current attempt. Honestly an observation rather than an assignment clock, because no assignment time is published to us. Null on an attempt that never had one.