> ## 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 <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.

# Efectivo en la puerta

> Cómo se le cobra en efectivo al cliente en la entrega, y en qué se liquida.

Manda `payment_method: "cash"` y el repartidor le cobra a tu cliente en la
puerta. En México la mayoría de los pedidos se siguen pagando así, de modo que
este es un camino de primera clase y no un respaldo: no necesita procesamiento
de tarjetas, ni alta de cuentas, ni un checkout propio.

## Qué cobra el repartidor

```
cash_to_collect_cents = order_value_cents + customer_fee_cents
```

El valor de la mercancía, más la parte de la tarifa de envío que decidiste que
paga el cliente. Nada más, y nunca la parte que pagas tú.

Tampoco una propina: `tip_cents` se rechaza en un pedido en efectivo, porque a un
repartidor en la puerta se le da la propina en la misma mano que ya le está
pasando dinero, y una propina declarada cambiaría este total y contaría para el
límite de efectivo de más abajo. Ve
[cotiza y crea](https://docs.listo.delivery/es/guides/quote-and-create.md).

Viene en la cotización y en el envío, como `payment.cash_to_collect_cents`:

```json theme={null}
{
  "order_value_cents": 19600,
  "fee_cents": 8004,
  "business_fee_cents": 0,
  "customer_fee_cents": 8004,
  "payment": {
    "method": "cash",
    "status": "unpaid",
    "cash_to_collect_cents": 27604,
    "paid_at": null
  }
}
```

Ese número queda fijo al crearse el envío. Ya no se mueve después, así que puedes
imprimirlo en un ticket o dictarlo por teléfono sin riesgo.

`null` y `0` son respuestas distintas aquí. En un pedido que no es en efectivo
el campo es `null`, porque no hay nada que cobrar y un `0` se leería como un
pedido gratis.

Un pedido en efectivo cuyo total en la puerta sí es cero reporta `0`. Eso pasa
cuando el valor del pedido es `0` y tú absorbes toda la tarifa de envío: el
pedido sigue siendo en efectivo, y lo que el repartidor cobra es nada. Su
`fee_cents` también coincide con lo que costaría un pedido prepagado del mismo
viaje, porque el efectivo que nunca se maneja no cuesta nada extra de manejar, y
el repartidor sale sin ningún cobro que hacer.

## El límite

A un repartidor se le puede pedir que cobre como máximo **MX\$1,000.00**, es
decir `100000` centavos, en `cash_to_collect_cents`. Ese es el total incluyendo
la parte del cliente, no solo el valor del pedido.

Por encima de eso, tanto la cotización como la creación se rechazan con
`422 cash_over_cap`. Hay dos maneras de librarlo:

* Tomar el pedido con `card`, que no tiene ese techo.
* Subir `business_fee_share` para que más de la tarifa salga de tu saldo y menos
  se cobre en la puerta. Esto solo ayuda cuando fue la tarifa la que empujó el
  total por encima.

> [!WARNING]
>
> **Un tope mueve el dinero al revés**
>
> `business_fee_cap_cents` sube el total de la puerta en lugar de bajarlo. Todo lo
> que el tope te impide absorber se le pasa a la parte del cliente, así que ponerle
> tope a lo que pagas aumenta `cash_to_collect_cents` exactamente en los centavos
> que rechazó.
>
> Un pedido que pasa el límite con puro porcentaje puede terminar rechazado con
> `cash_over_cap` en cuanto le pones un tope a ese mismo reparto. Si usas topes y
> cobras en efectivo, revisa el `cash_to_collect_cents` de la cotización en lugar
> de sacar la cuenta desde el porcentaje.

> [!WARNING]
>
> **Revisa el total, no el pedido**
>
> Un pedido de MX$980 con una tarifa de MX$80 que paga el cliente llega a MX\$1,060
> en la puerta y se rechaza. Si validas el límite por tu cuenta antes de cotizar,
> valida el total.

## Qué ve el cliente

Los pedidos en efectivo siempre se entregan en persona. Sea cual sea el
`handoff` que mandes, el repartidor se encuentra con el cliente en la puerta:
nadie deja tirado un pedido que hay que cobrar.

## Qué pasa con el dinero

El cliente le paga al repartidor, el efectivo regresa por la vía de Listo, y tu
saldo se abona con el **valor del pedido** cuando el envío queda en `delivered`.

La tarifa de envío nunca llega a tu saldo, porque nunca fue tuya: la parte del
cliente se cobró para Listo, y tu parte ya se había cargado al crear el envío.
Así que el efecto neto de un pedido en efectivo entregado es:

```
order_value_cents - business_fee_cents
```

que es exactamente lo que te habrías quedado si tú mismo hubieras cobrado y
hubieras pagado el envío.

Ese abono entra **retenido**. Cuenta en `balance_cents` de inmediato, así que
puedes gastarlo en el siguiente envío enseguida, y se suma a `available_cents`
una vez que ese efectivo ya se le liquidó a Listo, en un ciclo semanal. Ve
[saldo y retiros](https://docs.listo.delivery/es/guides/balance-and-withdrawals.md).

Si un envío termina en `returned`, el abono se revierte: el repartidor regresó
el pedido y no hay efectivo que registrar.

## `payment.status` se queda en `unpaid`

Vale la pena decirlo con todas sus letras, porque parece un error y no lo es.

En un pedido en efectivo, `payment.status` se queda en `unpaid` y `paid_at` se
queda en `null` durante toda la vida del envío, incluso después de entregado.
Ese campo describe dinero que pasa por Listo, y el efectivo nunca lo hace: va de
la mano de tu cliente a la del repartidor.

**`delivered_at` es la señal de que el efectivo se cobró.** Un envío en efectivo
con `delivered_at` es un envío en efectivo que se pagó. No esperes a que
`payment.status` cambie, porque nunca va a cambiar.

## Cuándo no es la opción correcta

* El total pasa de MX\$1,000. Cobra con tarjeta.
* Ya cobraste tú. Usa `prepaid`; no queda nada que cobrar y no hay razón para
  poner al repartidor a manejar dinero.


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