> ## Documentation Index > Fetch the complete documentation index at: https://docs.listo.delivery/llms.txt > Use this file to discover all available pages before exploring further. > ## 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 `. 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. # Lista tus movimientos del historial > Cada movimiento de tu saldo, los más nuevos primero, paginado por keyset. Es la superficie de conciliación: cierra un periodo recorriéndolo en lugar de sumar eventos de webhook, de modo que un evento que se te escapó, o uno que reenviaste, no cambia nada de lo que puedes reconstruir. `amount_cents` tiene signo: los abonos son positivos y los cargos negativos, y por eso una página suma el movimiento de tu saldo a lo largo de ella. Lee la dirección por ese signo y nunca por `type`. `type` indica de dónde viene un movimiento. El par que conviene conocer es el que produce un viaje desperdiciado: - `provider_charge` es la tarifa de envío cobrada por una cancelación tardía o un viaje de regreso, una tarifa por cada tramo recorrido, menos tu propio recargo como tienda. Es negativo y está ligado al pedido que lo causó. **Este monto cambió el 2026-08-29**: antes era lo que le costaba a Listo el viaje desperdiciado, así que espera valores más altos en los mismos pedidos desde esa fecha en adelante. La fila en sí no cambió. - `provider_charge_reversal` es ese cargo devuelto por completo, cuando resulta que el costo no se debía. Es positivo y se registra como una fila propia contra el mismo `delivery_id`, en lugar de como una reducción del cargo original, así que lo que te cobraron y lo que regresó siguen siendo legibles. Puede llegar semanas después del cargo. Empareja las dos por `delivery_id` y espera montos iguales y opuestos. Un tercer valor puede aparecer en el mismo pedido y es un monto distinto bajo otro encabezado: - `order_value_reimbursement` es el valor de un pedido que un repartidor recogió y que no llegó a nadie, abonado después de que lo reclamamos. Es positivo, ligado al pedido al que pertenece, y NO se empareja con ningún cargo en este historial: el valor del pedido nunca pasó por tu saldo, así que no hay nada que compensar. Se decide caso por caso y no está garantizado, así que nunca lo derives del total del pedido ni esperes uno por incidente. - `listo_charge_correction` es un cargo que Listo hizo por error y devolvió: un `provider_charge` que no te correspondía pagar. Es positivo, ligado al pedido que corrige, y se registra como una fila propia junto al cargo original, nunca como una reducción de este. Empárejalo con el cargo por `delivery_id`; puede ser menor que el cargo, y un pedido puede tener más de uno. Se decide caso por caso, así que nunca lo derives de un cargo ni esperes uno por cada cargo. - `requote_adjustment` es la diferencia entre la tarifa que se le cobró al pedido y la tarifa que la red de repartidores registró para el viaje, cuando las dos no son iguales. Tiene signo: negativo cuando el viaje registrado costó más de lo que te cobramos, positivo cuando costó menos. Va ligado al pedido, se registra como una fila propia junto al cargo del pedido y nunca como una reescritura de este, y un reintento del mismo pedido lo ajusta al viaje finalmente registrado en lugar de sumar otro. No se empareja con ninguna otra fila, y es poco común. Uno más es dinero que ganas, y es un abono: - `developer_share` es lo que ganas por un viaje entregado de tu propia tienda, abonado cuando el viaje se entrega. Es positivo, y está ligado al pedido al que pertenece. Un viaje cancelado o devuelto no genera nada. Otros dos son el Plan Listo de una tienda, pagados desde tu saldo: - `plan_charge` es un mes del plan de una tienda, con IVA incluido. Negativo. Un mes pagado con tarjeta no escribe fila, porque nunca tocó el saldo. - `plan_extra_charge` son las conversaciones del asistente de WhatsApp que pasan de lo que incluye el plan de una tienda `full`, cobradas a ti junto con el plan de esa tienda. Negativo. `store_id` indica a qué tienda pertenece un movimiento, en cada fila: la tienda del pedido, o la tienda cuyo plan se pagó. Es `null` cuando un movimiento no pertenece a una sola tienda, como una recarga o un retiro. Este vocabulario CRECE. Pueden aparecer valores nuevos en cualquier versión, porque v1 cambia de forma aditiva y un movimiento que todavía no sabes nombrar sigue siendo dinero que se movió. Así que ramifica según los valores que conoces y deja que el resto pase de largo: cuenta un `type` desconocido dentro del saldo, muéstralo, y no lo descartes ni lo rechaces. Las filas que descartas son la diferencia entre tus registros contables y `GET /v1/balance`. ## OpenAPI ````yaml /openapi/es.yaml get /v1/ledger openapi: 3.1.0 info: title: Listo Delivery API version: 1.34.0 description: > Cotiza un envío, despáchalo y sigue el recorrido hasta la puerta. Cada solicitud se autentica con una llave de API bearer. La llave misma decide el modo en el que actúa: una llave de prueba despacha repartidores simulados y no mueve dinero, y una llave real despacha repartidores reales. Una llave también puede ser de solo lectura: solo puede llamar a GET y HEAD, y cualquier otra llamada responde `403 read_only_key`. El dinero siempre va en pesos mexicanos y siempre en centavos enteros, y cada marca de tiempo es ISO-8601 en UTC. Los ids son cadenas opacas con prefijo (`st_` una tienda, `qt_` una cotización, `dlv_` un envío, `wd_` un retiro, `evt_` un evento, `le_` un movimiento del historial, `whd_` un intento de entrega de webhook, `req_` una llamada registrada). Trátalos como cadenas de longitud ilimitada y nunca los analices. Los cambios a v1 son aditivos: pueden aparecer campos nuevos y valores nuevos de enumeración, así que ignora lo que no reconozcas en lugar de fallar. servers: - url: https://api.listo.delivery security: [] tags: - name: Authentication description: Verifica que una llave funciona antes de empezar a construir con ella. x-group: Autenticación - name: Stores description: Las ubicaciones de recolección desde las que despachas. x-group: Tiendas - name: Account connection description: Conectar la cuenta de Listo que ya tiene un restaurante contigo. x-group: Conexión de cuenta - name: Quotes description: Lo que cuesta un envío, cotizado y retenido. x-group: Cotizaciones - name: Deliveries description: Despachar un pedido y seguirlo hasta la puerta. x-group: Envíos - name: Balance description: El saldo prepagado del que salen tus envíos. x-group: Saldo - name: Withdrawals description: Sacar dinero de ese saldo hacia tu banco. x-group: Retiros - name: Card onboarding description: Conectar la cuenta que recibe los pagos con tarjeta. x-group: Alta de cobros con tarjeta - name: Events description: >- Los eventos que Listo te envió, al reenviar uno y al enviar un evento de prueba a tu endpoint. x-group: Eventos - name: Webhook deliveries description: >- Cada intento que hizo Listo de enviar un evento a tu endpoint, y lo que respondió tu endpoint. x-group: Entregas de webhook - name: Request logs description: >- Cada llamada que hicieron tus llaves a esta API, con lo que enviaste y con lo que respondimos. x-group: Registro de solicitudes - name: Ledger x-group: Historial - name: Webhooks x-group: Webhooks paths: /v1/ledger: get: tags: - Ledger summary: Lista tus movimientos del historial description: > Cada movimiento de tu saldo, los más nuevos primero, paginado por keyset. Es la superficie de conciliación: cierra un periodo recorriéndolo en lugar de sumar eventos de webhook, de modo que un evento que se te escapó, o uno que reenviaste, no cambia nada de lo que puedes reconstruir. `amount_cents` tiene signo: los abonos son positivos y los cargos negativos, y por eso una página suma el movimiento de tu saldo a lo largo de ella. Lee la dirección por ese signo y nunca por `type`. `type` indica de dónde viene un movimiento. El par que conviene conocer es el que produce un viaje desperdiciado: - `provider_charge` es la tarifa de envío cobrada por una cancelación tardía o un viaje de regreso, una tarifa por cada tramo recorrido, menos tu propio recargo como tienda. Es negativo y está ligado al pedido que lo causó. **Este monto cambió el 2026-08-29**: antes era lo que le costaba a Listo el viaje desperdiciado, así que espera valores más altos en los mismos pedidos desde esa fecha en adelante. La fila en sí no cambió. - `provider_charge_reversal` es ese cargo devuelto por completo, cuando resulta que el costo no se debía. Es positivo y se registra como una fila propia contra el mismo `delivery_id`, en lugar de como una reducción del cargo original, así que lo que te cobraron y lo que regresó siguen siendo legibles. Puede llegar semanas después del cargo. Empareja las dos por `delivery_id` y espera montos iguales y opuestos. Un tercer valor puede aparecer en el mismo pedido y es un monto distinto bajo otro encabezado: - `order_value_reimbursement` es el valor de un pedido que un repartidor recogió y que no llegó a nadie, abonado después de que lo reclamamos. Es positivo, ligado al pedido al que pertenece, y NO se empareja con ningún cargo en este historial: el valor del pedido nunca pasó por tu saldo, así que no hay nada que compensar. Se decide caso por caso y no está garantizado, así que nunca lo derives del total del pedido ni esperes uno por incidente. - `listo_charge_correction` es un cargo que Listo hizo por error y devolvió: un `provider_charge` que no te correspondía pagar. Es positivo, ligado al pedido que corrige, y se registra como una fila propia junto al cargo original, nunca como una reducción de este. Empárejalo con el cargo por `delivery_id`; puede ser menor que el cargo, y un pedido puede tener más de uno. Se decide caso por caso, así que nunca lo derives de un cargo ni esperes uno por cada cargo. - `requote_adjustment` es la diferencia entre la tarifa que se le cobró al pedido y la tarifa que la red de repartidores registró para el viaje, cuando las dos no son iguales. Tiene signo: negativo cuando el viaje registrado costó más de lo que te cobramos, positivo cuando costó menos. Va ligado al pedido, se registra como una fila propia junto al cargo del pedido y nunca como una reescritura de este, y un reintento del mismo pedido lo ajusta al viaje finalmente registrado en lugar de sumar otro. No se empareja con ninguna otra fila, y es poco común. Uno más es dinero que ganas, y es un abono: - `developer_share` es lo que ganas por un viaje entregado de tu propia tienda, abonado cuando el viaje se entrega. Es positivo, y está ligado al pedido al que pertenece. Un viaje cancelado o devuelto no genera nada. Otros dos son el Plan Listo de una tienda, pagados desde tu saldo: - `plan_charge` es un mes del plan de una tienda, con IVA incluido. Negativo. Un mes pagado con tarjeta no escribe fila, porque nunca tocó el saldo. - `plan_extra_charge` son las conversaciones del asistente de WhatsApp que pasan de lo que incluye el plan de una tienda `full`, cobradas a ti junto con el plan de esa tienda. Negativo. `store_id` indica a qué tienda pertenece un movimiento, en cada fila: la tienda del pedido, o la tienda cuyo plan se pagó. Es `null` cuando un movimiento no pertenece a una sola tienda, como una recarga o un retiro. Este vocabulario CRECE. Pueden aparecer valores nuevos en cualquier versión, porque v1 cambia de forma aditiva y un movimiento que todavía no sabes nombrar sigue siendo dinero que se movió. Así que ramifica según los valores que conoces y deja que el resto pase de largo: cuenta un `type` desconocido dentro del saldo, muéstralo, y no lo descartes ni lo rechaces. Las filas que descartas son la diferencia entre tus registros contables y `GET /v1/balance`. operationId: listLedgerEntries parameters: - name: cursor in: query required: false schema: type: string example: 1785628920000000-1024 - name: delivery_id in: query required: false schema: type: string example: dlv_7hK2mQ9xR4tV6bN1cZ8sLwYe - name: type in: query required: false schema: type: string example: provider_charge responses: '200': description: La solicitud fue exitosa. content: application/json: schema: $ref: '#/components/schemas/LedgerEntryList' example: data: - id: le_3kR7pM1xV9tB4nQ6cW2sZdYe type: provider_charge amount_cents: -5800 delivery_id: dlv_7hK2mQ9xR4tV6bN1cZ8sLwYe store_id: st_4bR8kM2wQ7xT1nV5cZ9pLdYe test: false occurred_at: '2026-08-01T12:00:00Z' has_more: false cursor: null '401': description: >- La llave de API no existe, fue revocada o no es válida para este modo (`invalid_api_key`). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: invalid_api_key message: The API key is missing, revoked, or not valid for this mode. param: null retryable: false doc_url: https://docs.listo.delivery/en/errors/invalid_api_key request_id: 0b1f6c9a-7e2d-4c53-9a41-5d8e3f2a6b10 '404': description: >- Ningún objeto con ese id existe para esta llave (`not_found`). Los objetos de otra cuenta son indistinguibles de los que nunca existieron. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: 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 security: - BearerAuth: [] components: schemas: LedgerEntryList: type: object description: >- Una página de movimientos del historial, del más reciente al más antiguo. properties: data: type: array items: $ref: '#/components/schemas/LedgerEntry' has_more: type: boolean description: Verdadero cuando existe una página siguiente. cursor: type: - string - 'null' description: >- Pásalo como `cursor` para leer la siguiente página. Null en la última página. required: - data - has_more - cursor ErrorResponse: type: object description: El cuerpo de toda respuesta 4xx y 5xx de esta API. properties: error: $ref: '#/components/schemas/Error' required: - error LedgerEntry: type: object description: >- Un movimiento en un saldo. Los abonos son positivos y los cargos negativos. properties: id: type: string description: El id del movimiento, con prefijo `le_`. example: le_3kR7pM1xV9tB4nQ6cW2sZdYe type: type: string description: > De dónde viene el movimiento, como `provider_charge`, `provider_charge_reversal`, `developer_share`, `plan_charge` o `requote_adjustment`. El vocabulario CRECE: es a propósito una cadena simple, no una lista cerrada, así que decide con los valores que conoces y cuenta uno desconocido dentro del saldo. `GET /v1/ledger` describe cada valor. example: provider_charge amount_cents: type: integer description: Centavos con signo. Lee la dirección por el signo, nunca por `type`. delivery_id: type: - string - 'null' description: >- El id `dlv_` del que proviene el movimiento. Null para una recarga, un retiro o un ajuste. store_id: type: - string - 'null' description: >- El id `st_` de la tienda a la que pertenece el movimiento. Null cuando no pertenece a una sola tienda. test: type: boolean occurred_at: type: string format: date-time description: Cuándo se movió el dinero. required: - id - type - amount_cents - delivery_id - store_id - test - occurred_at Error: type: object description: > Cómo se ve todo rechazo y toda falla. `code` es el único campo en el que decidir; `message` es para una persona que lee un registro y puede cambiar de redacción o de idioma sin aviso. properties: code: type: string description: > Un nombre estable y legible por máquina de lo que salió mal, como `validation_failed`, `not_found` o `insufficient_balance`. Decide con base en esto y nunca en `message`. La lista crece sin romper nada: trata un código que no conozcas como el fallo genérico que indica su código de estado. Cada código tiene una página en `doc_url`. example: validation_failed message: type: string description: | Una oración para quien depura. Puede cambiar de redacción o de idioma en cualquier momento, así que nunca la uses para comparar. example: order_value_cents is required. param: type: - string - 'null' description: > El campo de la solicitud al que se refiere el rechazo, cuando aplica, escrito como lo enviaste (`dropoff.street`, `manifest.items`). Null cuando la falla no se refiere a un solo campo. example: order_value_cents retryable: type: boolean description: > Si volver a enviar la misma solicitud podría tener éxito. `false` significa que nunca lo tendrá sin un cambio de tu lado o en el mundo. example: false doc_url: type: string format: uri description: La página de documentación de este `code`. example: https://docs.listo.delivery/en/errors/validation_failed request_id: type: string description: > Nuestro id de esta solicitud, el mismo valor que el encabezado de respuesta `X-Request-Id`. Cítalo a soporte, y filtra `GET /v1/request_logs` por él. example: 0b1f6c9a-7e2d-4c53-9a41-5d8e3f2a6b10 required: - code - message - param - retryable - doc_url - request_id securitySchemes: BearerAuth: type: http scheme: bearer description: >- Tu llave de API, enviada como `Authorization: Bearer `. Las llaves reales y de prueba son distintas; la llave que envías decide en qué modo actúa la llamada. Para probar llamadas, usa una llave de prueba (empieza con `lst_test_`): no se envía ningún repartidor real y no se mueve dinero real, pero los webhooks se disparan y el `dropoff.phone` que des puede recibir mensajes de WhatsApp, así que usa tu propio número. Una llave real (empieza con `lst_live_`) reserva y cobra envíos reales. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.