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

# Complementos de tienda

> Extras de pago que activas o desactivas en cada una de tus tiendas, desde la API o el panel. Qué es cada uno, cuánto cuesta, cuándo se cobra y cómo leerlo en una tienda.

Un complemento es un extra de pago que activas en una tienda y desactivas cuando
quieras. Los complementos están disponibles para los partners con el precio de
autoservicio de Listo, en las tiendas que operas tú. Los cambias con
[`PATCH /v1/stores/{id}`](https://docs.listo.delivery/es/api-reference/stores/update-a-store) o desde la página
de la tienda en el [panel de socios](https://partners.listo.delivery); las
dos formas hacen lo mismo, y cada tienda tiene sus propios interruptores.

## Los complementos

Puedes activar tres. El precio es por tienda, antes de IVA, y a cada cobro se le
suma el IVA.

| Clave | Qué es | Precio | Se cobra |
| - | - | - | - |
| `customer_whatsapp` | Avisos por WhatsApp: Listo le cuenta al cliente por WhatsApp cómo va su viaje. | MX\$2 | por viaje entregado |
| `ratings` | Calificación de la comida: la calificación que el cliente da a la comida, en la entrega y por webhook. | MX\$99 | cada mes |
| `card_payments` | Ligas de pago con tarjeta. | MX\$5 | por pago realizado |

`add_ons` también lista `wallet` (Saldo del restaurante) y `full_console`
(Consola completa) con `available: false`. No se pueden activar: una petición que
pida cualquiera de los dos se rechaza y no se cobra nada.

Hay dos tipos de cobro:

* **Mensual** (`ratings`): se cobra cuando activas el complemento y otra vez el
  mismo día de cada mes.
* **Por uso** (`customer_whatsapp`, `card_payments`): nada por adelantado. Cada
  viaje entregado o cada pago con tarjeta realizado se cobra cuando ocurre.

## Cómo leer los complementos en una tienda

Cada objeto de tienda trae `add_ons`: la respuesta de la creación,
`GET /v1/stores/{id}`, cada fila de `GET /v1/stores`, la respuesta de la
actualización y la tienda que trae un evento `store.updated`. Viene en `null` en
una tienda a la que no le aplican los complementos. En las demás trae una entrada
por cada una de las cinco claves, siempre presentes:

```json theme={null}
{
  "id": "st_4bR8kM2wQ7xT1nV5cZ9pLdYe",
  "test": false,
  "add_ons": {
    "customer_whatsapp": {
      "status": "on",
      "price_cents": 200,
      "charged": "per_delivered_trip",
      "renews_on": null,
      "ends_on": null,
      "available": true
    },
    "ratings": {
      "status": "on",
      "price_cents": 9900,
      "charged": "monthly",
      "renews_on": "2026-12-07",
      "ends_on": null,
      "available": true
    },
    "card_payments": {
      "status": "off",
      "price_cents": 500,
      "charged": "per_paid_payment",
      "renews_on": null,
      "ends_on": null,
      "available": true
    },
    "wallet": {
      "status": "off",
      "price_cents": 19900,
      "charged": "monthly",
      "renews_on": null,
      "ends_on": null,
      "available": false
    },
    "full_console": {
      "status": "off",
      "price_cents": 199000,
      "charged": "monthly",
      "renews_on": null,
      "ends_on": null,
      "available": false
    }
  }
}
```

| Campo | Qué es |
| - | - |
| `status` | En qué punto está el complemento. La tabla siguiente. |
| `price_cents` | Lo que cuesta el complemento, en centavos y antes de IVA. |
| `charged` | Cuándo se cobra: `per_delivered_trip`, `monthly` o `per_paid_payment`. |
| `renews_on` | El día en que se cobra el siguiente mes de un complemento mensual que está activo. `null` en los demás casos. |
| `ends_on` | El último día que sigue funcionando un complemento mensual que desactivaste. `null` en los demás casos. |
| `available` | Si puedes activar este complemento en esta tienda. Es `false` para `wallet` y `full_console` en cualquier tienda. |

| `status` | Qué significa |
| - | - |
| `off` | No está activo. |
| `on` | Activo. Un complemento mensual está al corriente y se renueva en `renews_on`. |
| `ending` | Desactivaste un complemento mensual. Sigue funcionando hasta `ends_on`, el final del mes que pagaste. |

El `status` del esquema también lista `scheduled` y `past_due`. Aparecen solo en `wallet` y `full_console`, que hoy no se pueden activar, así que los tres complementos que sí puedes activar muestran solo `off`, `on` y `ending`.

## Activar y desactivar complementos

Manda en `add_ons` los complementos que quieras cambiar, cada uno como `true` o
`false`. Una clave que no mandes se queda como está.

```bash theme={null}
curl -X PATCH https://api.listo.delivery/v1/stores/st_4bR8kM2wQ7xT1nV5cZ9pLdYe \
  -H "Authorization: Bearer $LISTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "add_ons": { "ratings": true } }'
```

```json theme={null}
{
  "add_ons": {
    "ratings": true
  }
}
```

La respuesta es `200` con la tienda completa, `add_ons` incluido, en el estado en
que quedó. Cada clave se revisa antes de cambiar nada, así que una petición con
una clave incorrecta no cambia nada.

Algunas reglas:

* **`wallet` y `full_console` no se pueden activar.** Una petición que ponga
  cualquiera de los dos en `true` se rechaza con `422 validation_failed` y
  `param: "add_ons.wallet"` o `"add_ons.full_console"`, antes de cambiar o cobrar
  nada. Ponerlos en `false` se acepta.
* **Los complementos de cobro por uso** se activan y desactivan en la misma
  petición sin límite.

### Cuando no se puede pagar el primer mes

Activar un complemento mensual cobra su primer mes en la misma petición, de tu
saldo, o de tu tarjeta si elegiste tarjeta para los cobros del plan en la página
**Planes y facturación** del panel. Si no se puede pagar, la petición se
rechaza y no cambia nada: el complemento sigue desactivado y no se cobra nada.

```json theme={null}
{
  "error": {
    "code": "insufficient_balance",
    "message": "This add-on could not be paid: $50.00 available, $114.84 due including IVA. Nothing was charged and the add-on stays off.",
    "param": null,
    "retryable": false
  }
}
```

Recarga tu saldo o guarda una tarjeta y vuelve a mandar la petición. Manda un
`Idempotency-Key` para poder repetir sin cobrar dos veces una petición que se
agotó por tiempo.

## Renovaciones y desactivación

Un complemento mensual se cobra otra vez en `renews_on`, el mismo día de cada
mes, del mismo saldo o tarjeta.

* **Una renovación que no se puede pagar** desactiva el complemento al terminar el
  mes que ya pagaste. Recibes un correo y no se te debe nada. Puedes volver a
  activarlo cuando quieras, lo que cobra un mes nuevo.
* **Desactivar un complemento mensual** lo deja funcionando hasta el final del mes
  que pagaste: `status` queda en `ending` y `ends_on` nombra el último día. No se
  reembolsa nada y no se cobra nada más. Si lo vuelves a activar antes de
  `ends_on`, simplemente continúa, sin un cobro nuevo.

Los complementos por uso no tienen un mes que se termine. Activar o desactivar
uno surte efecto de inmediato.

## Cobros por uso

`customer_whatsapp` y `card_payments` se cobran de tu saldo cada vez que se usan:
`customer_whatsapp` cuando se entrega un viaje y `card_payments` cuando se paga
con tarjeta. Nunca se cobran a tu tarjeta. El reembolso de un pago con tarjeta no
devuelve sus MX\$5.

## En modo de prueba

Las tiendas de prueba pueden activar `customer_whatsapp`, `ratings` y
`card_payments`, los mismos tres que las tiendas en vivo. Los cobros por uso van a
tu saldo de prueba y no se cobra nada real. Ve [modo de prueba](https://docs.listo.delivery/es/concepts/test-mode.md).

## En tu libro de movimientos

Lo que los complementos cobran a tu saldo aparece en
[`GET /v1/ledger`](https://docs.listo.delivery/es/api-reference/ledger/list-your-ledger-entries):

| `type` | Qué es |
| - | - |
| `add_on_charge` | Un mes del complemento `ratings`, IVA incluido, pagado con tu saldo. Un mes pagado con tarjeta no mueve tu saldo y no escribe fila en el libro. |
| `customer_whatsapp_use` | Los avisos por WhatsApp de un viaje entregado. |
| `card_payments_use` | La liga de pago de un pago con tarjeta realizado. |

Ve [fondea tu saldo y retira](https://docs.listo.delivery/es/guides/balance-and-withdrawals.md).

## El evento `store.updated`

Cada cambio en los complementos de una tienda manda un evento `store.updated` con
el objeto completo de la tienda, `add_ons` incluido: un complemento activado,
desactivado o terminado. Lee los `add_ons` que trae cada evento en lugar de
contar eventos. Ve [webhooks](https://docs.listo.delivery/es/guides/webhooks.md).


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