# Listo Partner API

> Quote, create and track deliveries, and manage your balance, through the Listo Partner Delivery API.

> ## Agent Instructions
> Notes on the Listo Partner Delivery API:
> - Every endpoint is under `https://api.listo.delivery/v1/` and authenticates with a bearer API key.
> - This documentation site is at https://docs.listo.delivery. The full machine-readable reference is the OpenAPI document at https://api.listo.delivery/docs/openapi.yaml (served by the API host, not by this site).
> - Any page of this site is also available as raw markdown by appending `.md` to its URL, for example https://docs.listo.delivery/en/guides/webhooks.md. The index of every page is https://docs.listo.delivery/llms.txt and all of them in one file is https://docs.listo.delivery/llms-full.txt.
> - Every page is published in English under https://docs.listo.delivery/en/ and in Spanish under https://docs.listo.delivery/es/, with the same path after the language. The API reference is under https://docs.listo.delivery/api-reference/ in English and https://docs.listo.delivery/es/api-reference/ in Spanish.
> - To debug an integration yourself: `GET /v1/request_logs` lists the calls your keys made with what you sent and what was answered, `GET /v1/events` lists the events Listo emitted, `GET /v1/webhook_deliveries` lists every attempt to deliver them, `POST /v1/events/{id}/resend` sends one event again and `POST /v1/test_webhooks` sends a sample event (`"test": true`). The page https://docs.listo.delivery/en/guides/debugging describes them. A resent event is a snapshot from when it happened; `GET /v1/deliveries` is still how you recover current state.
> - Every error response has `error.doc_url`, a page that explains that error code and what to do, and `error.request_id`, the same value as the `X-Request-Id` response header. All the pages are listed at https://docs.listo.delivery/en/errors. Filter `GET /v1/request_logs` with `request_id` to read the logged call.
> - A `409 account_exists` from `POST /v1/stores` means the restaurant already has its own Listo account: connect it instead of creating it, as the page https://docs.listo.delivery/en/guides/connect-existing-account describes.
> - Every live store carries one Plan Listo, charged to the partner. The exception is a connected restaurant that had already paid its current month: it keeps paying its own plan until its next renewal, shown as `paid_by: "store"` with the handover date in `pending_paid_by_on`. A `402 plan_required` from a quote, a delivery create or a retry means the store's plan is not paid or has ended; the page https://docs.listo.delivery/en/guides/plan-and-billing describes the plan, the `plan` block on a store and how to end or restart it.
> - An AI assistant (Claude Code, Cursor, Codex) can act through the same API key at `https://api.listo.delivery/mcp`, an MCP server over Streamable HTTP authenticated with `Authorization: Bearer <API key>`. Every tool runs the matching `/v1/` endpoint, and each one that moves money first previews and then needs a confirmation token; the page https://docs.listo.delivery/en/guides/connect-ai-client lists the tools and describes the two steps.

## Get started

- [Quickstart](https://docs.listo.delivery/en/quickstart.md): Your first delivery, end to end, on a test key.

## Guides

- [Quote and create a delivery](https://docs.listo.delivery/en/guides/quote-and-create.md): Price a delivery, then turn the quote into a real one.
- [Receive and verify webhooks](https://docs.listo.delivery/en/guides/webhooks.md): Subscribe to delivery events, verify their signature, and respond.
- [Debugging your integration](https://docs.listo.delivery/en/guides/debugging.md): See every call you made, every event Listo emitted and every attempt to deliver it, then resend an event or send a test one.
- [Build with AI](https://docs.listo.delivery/en/guides/build-with-ai.md): Point a coding agent at the right files, give it a key that cannot move money, and start from prompts that name the exact pages to read.
- [Fund your balance and withdraw](https://docs.listo.delivery/en/guides/balance-and-withdrawals.md): Where the money for a delivery comes from, and how to take it out.
- [Go live](https://docs.listo.delivery/en/guides/go-live.md): What to check before you switch from a test key to a live one.
- [Connect a restaurant that already uses Listo](https://docs.listo.delivery/en/guides/connect-existing-account.md): Ask the owner to connect the Listo account they already have, instead of creating a second one.
- [Plan and billing](https://docs.listo.delivery/en/guides/plan-and-billing.md): Every live store carries one Plan Listo, and you pay for it. What it costs, when it is charged, how to read it, and how to end or restart it.
- [Connect Claude, Cursor or Codex](https://docs.listo.delivery/en/guides/connect-ai-client.md): Let your AI assistant quote, book, track and manage deliveries through your API key, with a confirmation step before anything moves money.

## Errors

- [Errors](https://docs.listo.delivery/en/errors/index.md): Every error code the Listo Partner API returns, what it means and what to do about it.
- [account_exists](https://docs.listo.delivery/en/errors/account_exists.md): That owner email already signs in to a Listo account, so a second store cannot be created for it.
- [address_not_found](https://docs.listo.delivery/en/errors/address_not_found.md): The address you sent as free text could not be located on a map.
- [address_undeliverable](https://docs.listo.delivery/en/errors/address_undeliverable.md): The dropoff address was rejected as one a courier cannot deliver to.
- [cancel_failed](https://docs.listo.delivery/en/errors/cancel_failed.md): The cancellation did not go through. Nothing changed, and the delivery is exactly as it was.
- [card_below_minimum](https://docs.listo.delivery/en/errors/card_below_minimum.md): The amount the customer owes by card is below the smallest card payment that can be charged.
- [card_not_ready](https://docs.listo.delivery/en/errors/card_not_ready.md): The store has no connected account that can accept card payments yet.
- [cash_over_cap](https://docs.listo.delivery/en/errors/cash_over_cap.md): The cash the courier would collect at the door is above the cash limit.
- [charge_in_progress](https://docs.listo.delivery/en/errors/charge_in_progress.md): A card charge for the store's plan is still being processed by the bank. Nothing new was charged.
- [code_expired](https://docs.listo.delivery/en/errors/code_expired.md): The connection code was exchanged after its 24 hours ran out.
- [console_access_required](https://docs.listo.delivery/en/errors/console_access_required.md): The store has no console, so there is no owner login to create.
- [event_not_resendable](https://docs.listo.delivery/en/errors/event_not_resendable.md): Courier location events are never sent again, because the next position replaces them within seconds.
- [idempotency_conflict](https://docs.listo.delivery/en/errors/idempotency_conflict.md): The idempotency key was already used with a different body, or the first request with that key is still running.
- [insufficient_balance](https://docs.listo.delivery/en/errors/insufficient_balance.md): The balance of the account that pays does not cover what this request would spend or move.
- [internal_error](https://docs.listo.delivery/en/errors/internal_error.md): Something failed on Listo's side. It is not a problem with your request.
- [invalid_api_key](https://docs.listo.delivery/en/errors/invalid_api_key.md): The API key on the request is missing, wrong, revoked, or belongs to a different mode than the thing you asked for.
- [no_couriers_available](https://docs.listo.delivery/en/errors/no_couriers_available.md): Every courier near the trip is busy right now, so no price came back. Nothing was created.
- [not_cancellable](https://docs.listo.delivery/en/errors/not_cancellable.md): The delivery or the plan is in a state that no longer allows cancelling.
- [not_editable](https://docs.listo.delivery/en/errors/not_editable.md): The dropoff instructions can no longer change on this delivery.
- [not_found](https://docs.listo.delivery/en/errors/not_found.md): There is no resource with that id for the API key you used.
- [not_reactivatable](https://docs.listo.delivery/en/errors/not_reactivatable.md): The store's plan has not ended, so there is nothing to reactivate.
- [not_refundable](https://docs.listo.delivery/en/errors/not_refundable.md): This order has no collected card payment left to give back.
- [not_reschedulable](https://docs.listo.delivery/en/errors/not_reschedulable.md): The delivery was already dispatched, so its pickup window can no longer be moved.
- [not_retriable](https://docs.listo.delivery/en/errors/not_retriable.md): Only a delivery that was left without a courier can be retried, and this one is not in that state.
- [order_too_large](https://docs.listo.delivery/en/errors/order_too_large.md): The cart is too large for one courier trip. Nothing was priced, created or charged.
- [out_of_service_area](https://docs.listo.delivery/en/errors/out_of_service_area.md): The dropoff address is outside the area Listo delivers to from this store.
- [payout_account_not_ready](https://docs.listo.delivery/en/errors/payout_account_not_ready.md): There is no bank account that can receive this withdrawal.
- [pickup_point_pending](https://docs.listo.delivery/en/errors/pickup_point_pending.md): The store's pickup point is not confirmed yet, so no courier can be requested from it. Nothing was created.
- [plan_ended](https://docs.listo.delivery/en/errors/plan_ended.md): The store's plan cancellation already took effect, so it can no longer be undone.
- [plan_required](https://docs.listo.delivery/en/errors/plan_required.md): This live store has no paid, active plan, so it cannot request couriers. Nothing was created.
- [provider_unavailable](https://docs.listo.delivery/en/errors/provider_unavailable.md): Dispatch is temporarily unavailable. Nothing was created.
- [quote_consumed](https://docs.listo.delivery/en/errors/quote_consumed.md): That quote was already used to create a delivery, and a quote can be used once.
- [quote_expired](https://docs.listo.delivery/en/errors/quote_expired.md): The quote you are creating a delivery from has expired.
- [rate_limited](https://docs.listo.delivery/en/errors/rate_limited.md): You sent too many requests in a short time. This request was not processed.
- [read_only_key](https://docs.listo.delivery/en/errors/read_only_key.md): The API key is read-only, and this request would create, change or cancel something. Reads still work with that key.
- [refund_amount_too_large](https://docs.listo.delivery/en/errors/refund_amount_too_large.md): The refund amount is more than this order has left to refund.
- [resend_limit_reached](https://docs.listo.delivery/en/errors/resend_limit_reached.md): This event was already sent again 5 times in the last hour.
- [same_day_below_minimum](https://docs.listo.delivery/en/errors/same_day_below_minimum.md): The amount is below the minimum for a same-day withdrawal.
- [same_day_cap_exceeded](https://docs.listo.delivery/en/errors/same_day_cap_exceeded.md): The account reached the same-day withdrawal limit for today.
- [test_webhook_limit_reached](https://docs.listo.delivery/en/errors/test_webhook_limit_reached.md): 30 test webhooks were already sent in the last hour for this mode.
- [unsupported_country](https://docs.listo.delivery/en/errors/unsupported_country.md): Listo delivers in Mexico only, and this address is in another country.
- [validation_failed](https://docs.listo.delivery/en/errors/validation_failed.md): A field of the request is missing, malformed or out of range. Nothing was created.
- [webhook_endpoint_not_configured](https://docs.listo.delivery/en/errors/webhook_endpoint_not_configured.md): There is no webhook URL set for this mode, so there is nowhere to send the event.

## Reference

### Balance

- [Read your prepaid balance](https://docs.listo.delivery/api-reference/balance/read-your-prepaid-balance.md): Your prepaid balance for the world the key acts in.
- [Read a store's balance](https://docs.listo.delivery/api-reference/balance/read-a-stores-balance.md)

### Account connection

- [Ask a restaurant to connect its account](https://docs.listo.delivery/api-reference/account-connection/ask-a-restaurant-to-connect-its-account.md): Starts the flow that connects a restaurant's EXISTING Listo account to you, and returns the link to put in front of its owner.
- [Exchange an approval for the store](https://docs.listo.delivery/api-reference/account-connection/exchange-an-approval-for-the-store.md): Exchanges the `code` from an approved connect request for the store it connected. What comes back is an ordinary store object, identical to what `POST /v1/stores` returns, and every store endpoint works on it immediately.

### Deliveries

- [List deliveries](https://docs.listo.delivery/api-reference/deliveries/list-deliveries.md): Your deliveries, newest first, keyset-paginated the same way stores are. Filter by `status`, `payment_status`, `store_id`, `external_id`, `created_after` and `created_before`.
- [Create a delivery](https://docs.listo.delivery/api-reference/deliveries/create-a-delivery.md): Dispatches a delivery.
- [Cancel a delivery](https://docs.listo.delivery/api-reference/deliveries/cancel-a-delivery.md): Cancels a delivery. Valid from every status except `delivered`, `canceled`, `returned` and `returning`.
- [Refund a delivery](https://docs.listo.delivery/api-reference/deliveries/refund-a-delivery.md)
- [Retry a failed dispatch](https://docs.listo.delivery/api-reference/deliveries/retry-a-failed-dispatch.md): Re-dispatches a delivery that ended at `no_courier`. It is priced and debited again, because it is a fresh dispatch, but the delivery id and your `external_id` are stable across retries: it stays the same order.
- [Fetch a delivery](https://docs.listo.delivery/api-reference/deliveries/fetch-a-delivery.md): Fetches one delivery by its `dlv_` id.
- [Update a delivery](https://docs.listo.delivery/api-reference/deliveries/update-a-delivery.md): Changes a delivery. It accepts exactly two fields, independently or together: `pickup_ready_at`, which moves a scheduled pickup, and `dropoff.notes`, which corrects what the courier is told about the drop-off. A body naming neither is a `422` on `pickup_ready_at`.

### Events

- [List your webhook events](https://docs.listo.delivery/api-reference/events/list-your-webhook-events.md): The events Listo emitted for you, newest first, keyset-paginated. Each item is the webhook envelope exactly as your endpoint is sent it (`id`, `type`, `created_at`, `data`), whether or not your endpoint received it, so you can compare what you stored with what we meant to tell you. An event you aske…
- [Send a webhook event again](https://docs.listo.delivery/api-reference/events/send-a-webhook-event-again.md): Sends one event to your webhook URL again. No request body. The answer is `202` with the event's envelope: the send happens right after, and its outcome is a new row on `GET /v1/webhook_deliveries` with `resent: true`, numbered after the event's last attempt.
- [Retrieve a webhook event](https://docs.listo.delivery/api-reference/events/retrieve-a-webhook-event.md): One event, as the envelope your endpoint is sent. An event that is not yours, or belongs to the other mode, is `404 not_found`.
- [Send a test webhook](https://docs.listo.delivery/api-reference/events/send-a-test-webhook.md): Sends a synthetic event of one published `type` to your webhook URL, so you can exercise an endpoint without placing an order. The answer is `202` with the event as your endpoint receives it, and the attempt appears on `GET /v1/webhook_deliveries` like any other.

### Ledger

- [List your ledger entries](https://docs.listo.delivery/api-reference/ledger/list-your-ledger-entries.md): Every movement on your balance, newest first, keyset-paginated. This is the reconciliation surface: close a period by walking it rather than by adding up webhook events, so an event you missed, or one you had resent, changes nothing about what you can rebuild.
- [List a store's ledger entries](https://docs.listo.delivery/api-reference/ledger/list-a-stores-ledger-entries.md)

### Authentication

- [Check that your API key works](https://docs.listo.delivery/api-reference/authentication/check-that-your-api-key-works.md): Confirms that a key is valid and tells you which world it acts in. Build against this first: it exercises authentication, rate limiting and the error envelope without creating anything.

### Quotes

- [Price a delivery](https://docs.listo.delivery/api-reference/quotes/price-a-delivery.md): Prices a trip and holds that price for you to bind. The price is set at the moment you ask for the quote: bind its `id` on the delivery create and the order is charged the `fee_cents` and the split you were shown.

### Request logs

- [List your request log](https://docs.listo.delivery/api-reference/request-logs/list-your-request-log.md): Every call your keys made to this API, newest first, keyset-paginated like every list here. Use it to answer "what did my code send, and what did Listo say?" without asking anyone.
- [Retrieve a request log entry](https://docs.listo.delivery/api-reference/request-logs/retrieve-a-request-log-entry.md): One call, with what it sent (`request_body`) and what Listo answered (`response_body`), both as JSON. For a failure, the answer is the error envelope you received and the request is what actually went over the wire.

### Stores

- [List your stores](https://docs.listo.delivery/api-reference/stores/list-your-stores.md): Your stores, newest first, keyset-paginated. Pass the `cursor` from the previous page to continue; `has_more` tells you when to stop. There is no total count, by design.
- [Create a store](https://docs.listo.delivery/api-reference/stores/create-a-store.md): Registers a pickup location. `lat`/`lng` are optional; send them when you have them and we take them as given, otherwise we geocode `street`.
- [Fetch a store](https://docs.listo.delivery/api-reference/stores/fetch-a-store.md): Fetches one store by its `st_` id.
- [Update a store](https://docs.listo.delivery/api-reference/stores/update-a-store.md): Updates a store. Send only the fields you are changing. Existing deliveries are unaffected: the pickup name, street and coordinates are snapshotted onto each delivery when it is created, so a rename or a move never rewrites where a past courier actually went.
- [Invite a store owner](https://docs.listo.delivery/api-reference/stores/invite-a-store-owner.md): Gives the person who runs the store a login to its Listo console. We create the login and email them a link to choose their own password. The response carries the address the link went to and when it was sent, and never a password or a token, so there is nothing in it to store.
- [Reactivate a store's plan](https://docs.listo.delivery/api-reference/stores/reactivate-a-stores-plan.md): Restarts a plan that ended. The first month is charged in this request, from your live balance or your saved card, and the response is the store with `plan.status` `active`.
- [Cancel a store's plan](https://docs.listo.delivery/api-reference/stores/cancel-a-stores-plan.md): Cancels the store's Plan Listo at the end of the period already paid. Nothing is charged again, the store keeps its couriers up to the day before `plan.ends_on`, and from that day its quotes and deliveries are refused with `402 plan_required`. The response is the store, with `plan.status` `canceling…
- [Undo a store's plan cancellation](https://docs.listo.delivery/api-reference/stores/undo-a-stores-plan-cancellation.md): Undoes a cancellation before it takes effect. The plan goes back to `active` and renews on its usual day, and nothing is charged now. A plan that is not being canceled answers `200` with the store as it is, so the call is safe to repeat.

### Card onboarding

- [Start card onboarding for a store](https://docs.listo.delivery/api-reference/card-onboarding/start-card-onboarding-for-a-store.md): Starts card onboarding for one store, and returns a one-time hosted link to send its owner. The store is then the merchant of record for its own card charges. This is the usual choice.
- [Read a store's card readiness](https://docs.listo.delivery/api-reference/card-onboarding/read-a-stores-card-readiness.md): Whether this store can take card payments yet, and what is still outstanding if not.
- [Start card onboarding for your company](https://docs.listo.delivery/api-reference/card-onboarding/start-card-onboarding-for-your-company.md): Starts card onboarding for your company, and returns a one-time hosted link to send whoever can answer for the business. Complete it once and every store you own can take card payments.
- [Read your company's card readiness](https://docs.listo.delivery/api-reference/card-onboarding/read-your-companys-card-readiness.md): Whether your company can take card payments yet, and what is still outstanding if not. Re-read this after a `store.updated` webhook: card readiness is never a field on the store object.

### Webhook deliveries

- [List webhook delivery attempts](https://docs.listo.delivery/api-reference/webhook-deliveries/list-webhook-delivery-attempts.md): Every attempt Listo made to POST an event to your webhook URL, newest first, keyset-paginated: the URL, the status your endpoint answered with, the first 500 characters of its body, how long it took and whether it counted as a success. An event has one attempt per try: the first send, each automatic…

### Withdrawals

- [List your withdrawals](https://docs.listo.delivery/api-reference/withdrawals/list-your-withdrawals.md): Your withdrawal requests, newest first, keyset-paginated.
- [Request a withdrawal](https://docs.listo.delivery/api-reference/withdrawals/request-a-withdrawal.md): Requests a transfer of `amount_cents` out of your balance to your registered bank account. The money is reserved the moment the request is accepted, so a second request cannot spend it twice.
- [Fetch a withdrawal](https://docs.listo.delivery/api-reference/withdrawals/fetch-a-withdrawal.md): Fetches one withdrawal by its `wd_` id, which is how you check on one that has not resolved yet without waiting for its webhook.

### Webhooks

- [A delivery reached a new status](https://docs.listo.delivery/api-reference/webhooks/a-delivery-reached-a-new-status.md): Sent on every status transition, including the ones you did not cause: a courier accepting the order, a card payment landing, a dispatch failing, a courier or our platform calling the trip off.
- [A delivery changed without changing status](https://docs.listo.delivery/api-reference/webhooks/a-delivery-changed-without-changing-status.md): Sent when something you can see about a delivery moved but its status did not: the courier's identity arrived, an ETA shifted, the courier became imminent, proof of delivery landed, or a payment was refunded.
- [The courier moved](https://docs.listo.delivery/api-reference/webhooks/the-courier-moved.md): The courier position ping, roughly every twenty seconds while a trip is in motion. Consume it if you render your own map; the branded `tracking_url` on the delivery is the alternative that needs no integration at all.
- [A withdrawal was settled](https://docs.listo.delivery/api-reference/webhooks/a-withdrawal-was-settled.md): Sent when a withdrawal stops being a request: it was paid, or it failed. A withdrawal that is still `pending` announces nothing, because you already hold that state as the create response.
- [A store changed](https://docs.listo.delivery/api-reference/webhooks/a-store-changed.md): Sent when one of your stores changes, including changes nobody asked for. The headline case is card readiness flipping once the hosted onboarding is reviewed. A change to a live store's Plan Listo sends one too, carrying the `plan`: a plan that starts, renews, fails or clears a charge, is canceled o…
- [A restaurant connected its existing account to you](https://docs.listo.delivery/api-reference/webhooks/a-restaurant-connected-its-existing-account-to-you.md): Sent when the owner of an existing Listo account approves your connect request. `data` is the whole store object, so this is everything `POST /v1/connections` would have told you.

## Concepts

- [The money model](https://docs.listo.delivery/en/concepts/money.md): Who pays for a delivery, and how the balance is kept.
- [Where a delivery came from](https://docs.listo.delivery/en/concepts/delivery-origin.md): Why deliveries you did not create appear at your stores, and how to tell them apart.
- [Test mode](https://docs.listo.delivery/en/concepts/test-mode.md): What a test key does differently, and what it does not.
- [Signing](https://docs.listo.delivery/en/concepts/signing.md): How webhook signatures are built and how to verify them.
- [Cash at the door](https://docs.listo.delivery/en/concepts/cash-at-the-door.md): Collecting cash from the customer on delivery, and what it settles to.

## Changelog

- [Changelog](https://docs.listo.delivery/en/changelog.md): Every change to the Partner Delivery API, newest first.

## Legal

- [Terms for Partners](https://docs.listo.delivery/en/terms-for-partners.md)

## OpenAPI Specs

- [en](/openapi/en.yaml)

> The links below point to documentation indexes. Follow each `/_llms/` index recursively until you reach documentation pages.

## Indexes

- [Spanish (103 pages)](https://docs.listo.delivery/_llms/es.txt): Documentation for Spanish.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.