Quote and create a delivery

# Prices a delivery, then dispatches it at the price it was quoted.
#
#   LISTO_API_KEY=lst_test_... LISTO_STORE_ID=st_... ruby quote_and_create.rb
#
require "json"
require "net/http"
require "uri"

BASE_URL = ENV.fetch("LISTO_API_BASE_URL", "https://api.listo.delivery")
API_KEY = ENV.fetch("LISTO_API_KEY")
STORE_ID = ENV.fetch("LISTO_STORE_ID")

# Your own reference for this order. It is what you will recognise the delivery
# by in every response and every webhook, so use the id your system already has.
ORDER_ID = "order-841"

# The refusal envelope every Listo error carries, or a stand-in built from the
# status when the body is not that envelope at all. Something between you and
# Listo, a proxy or a load balancer, can answer with an HTML error page or with
# JSON of some other shape, and the code that handles a failure must not itself
# fail trying to read it.
def parse_error(response)
  stand_in = {"code" => "HTTP #{response.code}", "param" => nil}
  body = JSON.parse(response.body.to_s)
  error = body["error"] if body.is_a?(Hash)
  error.is_a?(Hash) ? error : stand_in
rescue JSON::ParserError
  stand_in
end

def post(path, payload, headers = {})
  uri = URI("#{BASE_URL}#{path}")

  request = Net::HTTP::Post.new(uri)
  request["Authorization"] = "Bearer #{API_KEY}"
  request["Content-Type"] = "application/json"
  headers.each { |name, value| request[name] = value }
  request.body = JSON.generate(payload)

  response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
    http.request(request)
  end

  # Check the status BEFORE parsing the body. Every refusal from Listo answers
  # with the same envelope, so branch on `error.code`, never on the message, and
  # retry only when `error.retryable` says you may.
  unless response.code.start_with?("2")
    abort("POST #{path} refused: #{parse_error(response)["code"]}")
  end

  JSON.parse(response.body)
end

dropoff = {
  "name" => "Ana Torres",
  "phone" => "+528112345678",
  "street" => "Blvd. Puerta de Hierro 4965, Zapopan, Jalisco 45116",
  "lat" => 20.709395,
  "lng" => -103.413393
}

# 1. Ask what the delivery costs. The price is held until `expires_at`, so you
# can show it to your customer before anyone commits to anything. No money
# moves and no courier is called.
quote = post(
  "/v1/quotes",
  {
    "store_id" => STORE_ID,
    "payment_method" => "cash",
    "order_value_cents" => 19_600,
    "dropoff" => dropoff
  }
)

puts "fee #{quote["fee_cents"]} #{quote["currency"]}, of which you pay #{quote["business_fee_cents"]}"
puts "the courier collects #{quote["cash_to_collect_cents"]} at the door"

# 2. Dispatch it at exactly that price by sending the quote id back.
#
# The Idempotency-Key is REQUIRED. Send the same one again after a timeout and
# you get the original delivery back instead of a second courier; send it with
# a different body and the call is refused with `idempotency_conflict`. Key it
# on your order, not on the attempt.
delivery = post(
  "/v1/deliveries",
  {
    "store_id" => STORE_ID,
    "quote_id" => quote["id"],
    "external_id" => ORDER_ID,
    "payment_method" => "cash",
    "order_value_cents" => 19_600,
    "dropoff" => dropoff
  },
  {"Idempotency-Key" => "create-#{ORDER_ID}"}
)

puts "delivery #{delivery["id"]} is #{delivery["status"]}"
puts "follow it at #{delivery["tracking_url"] || "(no link until a courier is assigned)"}"

​

The quote

• Creating against an expired quote returns 400 quote_expired. Ask for a new one and try again; nothing was created.
• A quote is single use. Spending it twice returns 400 quote_consumed, which is what a duplicate submit looks like from here.

​

The create

​

Idempotency-Key is required

​

external_id is how you will recognise it

​

Payment methods

• POST /v1/quotes with prepaid refuses a business_fee_share other than 100 with 422 validation_failed naming business_fee_share. Send 100 or leave it out: with no split fields the quote is priced at 100, whatever your store’s default split is. A quote that names no payment_method is priced exactly the same way, because the only delivery that can bind it is a prepaid one: it refuses a share other than 100 too, with a message that says so and that you can name the payment_method instead. To split the fee with your customer, quote as cash or card.
• POST /v1/deliveries with prepaid and no quote_id forces the share to 100 and creates the order.
• POST /v1/deliveries with prepaid and a quote_id needs a quote that was requested with payment_method: prepaid or with no payment_method, either of which is always priced at 100. Any other quote is refused with 422 validation_failed, naming the first thing that does not match. A quote requested as cash or card is refused naming payment_method. A quote whose split is not 100 with no ceiling (one saved before this rule) is refused naming business_fee_share (or business_fee_cap_cents), with a message that says to request a new quote as prepaid.

​

What Listo sends your customer

• The payment link, on card orders. The moment a card order is created and waits for payment, Listo sends the customer a WhatsApp with their first name, your store’s name, what they owe and the payment.url link, and says the courier leaves as soon as they pay. If that WhatsApp does not reach them (the number is not on WhatsApp, or the message fails), Listo sends the same link by SMS instead, from a short code, so they still get it. It is sent once per order, with nothing for you to call. A link that is no longer live, because the order was paid or cancelled, is not sent.
• The courier’s messages, on every order. Once a courier is assigned, when they are on the way, when they are arriving and when the order is delivered, Listo sends the customer a WhatsApp from the same number, with the tracking link and, if you asked for one, the drop-off code. This includes prepaid and cash orders: paying in your own checkout does not stop Listo from telling the customer where their order is.

​

Tipping the courier

​

Scheduling

​

Sending it by car

• A car is a sedan. We can guarantee a car, never a van.
• There are fewer cars than motorcycles, so a car can take longer to assign.
• A car adds a surcharge to the delivery fee. It is inside fee_cents and split like the rest of the fee, so the price you are quoted is the whole price, and there is no separate line for it.

​

The optional detail

• manifest.items is a list of {name, quantity, size} for the courier to check against. It is descriptive: money comes from order_value_cents, and the one thing an item can change is the vehicle, through its size (see sending it by car).
• handoff is meet_at_door (the default), leave_at_door or meet_outside. Cash orders are always handed over in person.
• dropoff.notes are per-order instructions for this address, at most 280 characters. Standing instructions for the store belong on the store as pickup_notes.
• verification.dropoff_pincode: true asks for a code the customer has to give the courier. It comes back on the delivery as verification.pincode once a courier has one. Listo also gives it to your customer in its own courier messages, so you only need to show it yourself if you want it on your screen.
• dropoff.lat and dropoff.lng are optional. Leave them out and the street is located for you; send them and they are used as given. Send both or neither.

​

When an order comes back: the return code

{
  "status": "returning",
  "return_verification": { "pincode": "4821" }
}

• return_verification is always on the object. pincode is a 4 digit string while status is returning, and null in every other state, so show the code when it is there and hide it when it is not.
• You do not need to poll for it. The delivery.status_changed webhook for the move to returning carries the whole delivery object, code included (see webhooks).
• It is the store’s code, never the customer’s, and it is not verification.pincode, which is the drop-off code the customer gives the courier. Do not send it to your customer.
• Staff should give it to the courier only once they have the order in hand.
• Each attempt has its own code. A retried delivery is a new attempt, so it gets a new code.
• Once the delivery is returned the code is spent and pincode goes back to null.

​

What you get back

​

When it is refused

{
  "error": {
    "code": "out_of_service_area",
    "message": "The dropoff address is outside the delivery service area.",
    "param": null,
    "retryable": false
  }
}

​

After it is dispatched

• GET /v1/deliveries/{id} reads one back, and GET /v1/deliveries lists them newest first, filtered by status, payment_status, store_id, external_id, origin and a created window, and paged with an opaque cursor.
• POST /v1/deliveries/{id}/cancellations calls it off, with a reason from Listo’s own list: customer_canceled, store_closed, item_unavailable, wrong_address, no_longer_needed, or other with a description. It works from any non-final state, and cancelling an already cancelled delivery simply answers with it.
• POST /v1/deliveries/{id}/retries re-dispatches a delivery that ended at no_courier. The id and your external_id survive the retry, so it stays one order to you. If the courier network refuses the retried delivery’s distance at the edge of the service area, the retry answers 422 out_of_service_area, which is final: the delivery stays at no_courier and nothing is charged.