> ## 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. # Consulta tu saldo prepagado > Tu saldo prepagado para el modo en el que actúa la llave. `balance_cents` es todo lo que hay en la cuenta. `available_cents` es lo que puedes retirar hoy, que es menor siempre que el efectivo cobrado en las puertas de los clientes todavía no nos haya llegado. Gastar no depende de `available_cents`; retirar sí. `in_review_cents` es la parte de `balance_cents` que es efectivo de un pedido que aún estamos revisando. Siempre está presente, `0` cuando no hay nada en revisión, y ya queda excluido de `available_cents`. No se puede adelantar, y un envío no se puede pagar con él, así que una creación puede responder `402 insufficient_balance` mientras `balance_cents` por sí solo parece suficiente: `balance_cents` menos `in_review_cents` es con lo que los envíos pueden contar. Se mueve cuando tenemos una respuesta, no en una fecha. ### La oferta del mismo día `same_day` describe lo que te costaría ahora mismo un retiro `same_day` (`POST /v1/withdrawals`) y de qué tamaño podrías pedirlo, para que muestres la opción en lugar de descubrirla con un rechazo. Todos los campos siempre están presentes. `ceiling_cents` es el `amount_cents` más grande por el que una solicitud del mismo día sería aceptada en este momento. **No es otro nombre de `available_cents`**: el techo ya descuenta `fee_cents` y ya se ajustó a lo que queda del día, y puede alcanzar efectivo todavía retenido que `available_cents` excluye por definición. En una cuenta es el mayor de los dos y en otra el menor, así que ninguno se deriva del otro. `reach_cents` es todo lo que la solicitud podría tomar antes de la tarifa, y `advanceable_cents` es la parte de eso que todavía es efectivo retenido. `cap_cents`, `cap_used_cents` y `cap_remaining_cents` son el máximo diario por cuenta y la posición de hoy frente a él, y `minimum_cents` es el piso por solicitud. `window_open` dice si el equipo está enviando en este momento. `due_at` es la fecha límite que llevaría una solicitud hecha en el momento en que lees esto, y `next_window_opens_at` es la siguiente vez que se reanuda el envío; la fecha límite que de verdad lleva tu solicitud es el `due_at` del objeto de retiro que devuelve. Las solicitudes se aceptan a cualquier hora de todos modos. `offerable` es false cuando no se aceptaría ninguna solicitud del mismo día, y `unavailable_reason` dice en cuál de los dos estados estás: `cap_reached` (el máximo de hoy ya se gastó, y vuelve mañana por la mañana) o `below_minimum` (el alcance es demasiado pequeño para superar el piso más la tarifa). Es null siempre que `offerable` sea true. ## OpenAPI ````yaml /openapi/es.yaml get /v1/balance 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/balance: get: tags: - Balance summary: Consulta tu saldo prepagado description: > Tu saldo prepagado para el modo en el que actúa la llave. `balance_cents` es todo lo que hay en la cuenta. `available_cents` es lo que puedes retirar hoy, que es menor siempre que el efectivo cobrado en las puertas de los clientes todavía no nos haya llegado. Gastar no depende de `available_cents`; retirar sí. `in_review_cents` es la parte de `balance_cents` que es efectivo de un pedido que aún estamos revisando. Siempre está presente, `0` cuando no hay nada en revisión, y ya queda excluido de `available_cents`. No se puede adelantar, y un envío no se puede pagar con él, así que una creación puede responder `402 insufficient_balance` mientras `balance_cents` por sí solo parece suficiente: `balance_cents` menos `in_review_cents` es con lo que los envíos pueden contar. Se mueve cuando tenemos una respuesta, no en una fecha. ### La oferta del mismo día `same_day` describe lo que te costaría ahora mismo un retiro `same_day` (`POST /v1/withdrawals`) y de qué tamaño podrías pedirlo, para que muestres la opción en lugar de descubrirla con un rechazo. Todos los campos siempre están presentes. `ceiling_cents` es el `amount_cents` más grande por el que una solicitud del mismo día sería aceptada en este momento. **No es otro nombre de `available_cents`**: el techo ya descuenta `fee_cents` y ya se ajustó a lo que queda del día, y puede alcanzar efectivo todavía retenido que `available_cents` excluye por definición. En una cuenta es el mayor de los dos y en otra el menor, así que ninguno se deriva del otro. `reach_cents` es todo lo que la solicitud podría tomar antes de la tarifa, y `advanceable_cents` es la parte de eso que todavía es efectivo retenido. `cap_cents`, `cap_used_cents` y `cap_remaining_cents` son el máximo diario por cuenta y la posición de hoy frente a él, y `minimum_cents` es el piso por solicitud. `window_open` dice si el equipo está enviando en este momento. `due_at` es la fecha límite que llevaría una solicitud hecha en el momento en que lees esto, y `next_window_opens_at` es la siguiente vez que se reanuda el envío; la fecha límite que de verdad lleva tu solicitud es el `due_at` del objeto de retiro que devuelve. Las solicitudes se aceptan a cualquier hora de todos modos. `offerable` es false cuando no se aceptaría ninguna solicitud del mismo día, y `unavailable_reason` dice en cuál de los dos estados estás: `cap_reached` (el máximo de hoy ya se gastó, y vuelve mañana por la mañana) o `below_minimum` (el alcance es demasiado pequeño para superar el piso más la tarifa). Es null siempre que `offerable` sea true. operationId: getBalance responses: '200': description: La solicitud fue exitosa. content: application/json: schema: $ref: '#/components/schemas/Balance' example: balance_cents: 400000 available_cents: 268400 currency: MXN same_day: fee_cents: 3000 minimum_cents: 10000 ceiling_cents: 397000 reach_cents: 400000 advanceable_cents: 131600 cap_cents: 500000 cap_used_cents: 0 cap_remaining_cents: 500000 window_open: true due_at: '2026-07-30T21:30:00Z' next_window_opens_at: '2026-07-31T14:00:00Z' offerable: true unavailable_reason: null in_review_cents: 0 '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 security: - BearerAuth: [] components: schemas: Balance: type: object description: Tu saldo prepagado para el mundo en el que actúa la llave. properties: balance_cents: type: integer description: Todo lo que hay en la cuenta, en centavos. available_cents: type: integer description: Lo que puedes retirar hoy. Gastar no depende de esto. currency: type: string enum: - MXN same_day: $ref: '#/components/schemas/SameDayTerms' in_review_cents: type: integer description: > La parte de `balance_cents` que es efectivo de un pedido que aún revisamos. `0` cuando no hay nada en revisión. Ya está excluida de `available_cents`, y un envío no puede pagarse con ella. required: - balance_cents - available_cents - in_review_cents - currency - same_day ErrorResponse: type: object description: El cuerpo de toda respuesta 4xx y 5xx de esta API. properties: error: $ref: '#/components/schemas/Error' required: - error SameDayTerms: type: object description: | Cuánto te costaría un retiro `same_day` y de qué tamaño podrías pedirlo, ahora mismo. Todos los campos siempre están presentes. properties: fee_cents: type: integer description: >- Lo que cuesta un retiro del mismo día, con IVA incluido, que se cobra sobre el monto. minimum_cents: type: integer description: >- El `amount_cents` más bajo por el que se acepta una solicitud del mismo día. ceiling_cents: type: integer description: > El `amount_cents` más alto por el que una solicitud del mismo día sería aceptada en este momento. No es otro nombre para `available_cents`. reach_cents: type: integer description: Todo lo que una solicitud podría usar antes de la tarifa. advanceable_cents: type: integer description: La parte de `reach_cents` que es efectivo aún retenido. cap_cents: type: integer description: El máximo diario por cuenta. cap_used_cents: type: integer description: Cuánto del máximo diario ya se usó hoy. cap_remaining_cents: type: integer description: Lo que queda del máximo diario hoy. window_open: type: boolean description: Si el equipo está enviando transferencias en este momento. due_at: type: string format: date-time description: >- El plazo que llevaría una solicitud hecha en el momento en que lees esto. next_window_opens_at: type: string format: date-time description: La próxima vez que se reanudan los envíos. offerable: type: boolean description: Falso cuando no se aceptaría ninguna solicitud del mismo día. unavailable_reason: type: - string - 'null' enum: - cap_reached - below_minimum - null description: > Por qué `offerable` es falso: `cap_reached` (el máximo de hoy ya se gastó) o `below_minimum` (el alcance es demasiado pequeño para cubrir el mínimo más la tarifa). Null siempre que `offerable` sea verdadero. required: - fee_cents - minimum_cents - ceiling_cents - reach_cents - advanceable_cents - cap_cents - cap_used_cents - cap_remaining_cents - window_open - due_at - next_window_opens_at - offerable - unavailable_reason 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.