> ## 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. # Plan and billing > 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. Every store you run in live mode carries one Plan Listo, and the plan is charged to you. One plan per store, whatever the store's `access_tier`, and whether the store is a location of your own or a restaurant you integrate for. Listo never charges the restaurant for a plan you pay, and never learns what you charge it: bill your own clients however you like. Some partners' agreements with Listo work the other way: each restaurant pays its own Plan Listo, and you pay nothing for it. If that is your agreement, Listo has set it on your account and the rest of this page about charges to you does not apply to you. [Where each restaurant pays its own plan](#where-each-restaurant-pays-its-own-plan) says what changes. If you are not sure which one you have, ask Listo. A live store without a paid-up plan cannot request couriers. Test stores have no plan, never pay one and are never refused for lack of one. ## What a plan costs At list price, Plan Listo is MX\$1,990 plus IVA a month for each store: `199000` cents before IVA, `230840` with it. If you agreed a different price with Listo, every one of your stores is charged the price agreed with Listo instead. A price is per store and never pooled. Ten live stores are ten plans, each with its own renewal date and its own charge. When your agreed price changes, the change reaches each store at its next renewal. The month a store already paid for does not move, and a store you create after the change starts at the new price. Listo emails you when it happens. The plan covers the couriers, the Listo console and the WhatsApp AI assistant for that store. A store on the `full` tier that runs the assistant past the conversations its plan includes is charged for those too, and they are charged to you along with that store's plan. ## When it is charged The plan starts the day you create the store with a live key, and the first month is charged in that same request. If your balance and card cannot cover that first charge, the store is still created but the plan has not started: it starts the day that charge is paid ([when the first charge cannot be paid](#when-the-first-charge-cannot-be-paid)). From then on it renews every month on the same day of the month. A store created on the 29th, 30th or 31st moves to an earlier day the first time a month is shorter, and stays there. While the plan is paid up, `next_charge_on` on the store carries the exact date. Each charge is paid from your live balance or from the card saved on your account, whichever you choose on the **Planes y facturación** page of the [partner dashboard](https://partners.listo.delivery), with the other one as an optional backup when the first cannot pay. It is never paid from a store's own balance, and never from your test balance. A month paid from the balance spends against `balance_cents`, exactly as a delivery does, and appears on [`GET /v1/ledger`](https://docs.listo.delivery/api-reference/ledger/list-your-ledger-entries) as a `plan_charge` row with the whole amount, IVA included, the store in `store_id` and a `delivery_id` of `null`. A month paid by card moves nothing on your balance and writes no ledger row. See [balance and withdrawals](https://docs.listo.delivery/en/guides/balance-and-withdrawals.md). > [!WARNING] > > **A live store create spends money now** > > `POST /v1/stores` with a live key charges the store's first month in the same > request, and the plan starts there only if that charge goes through; otherwise the > store waits and the plan starts the day it is paid. Fund your live balance or save a card before you create a store, and > send an `Idempotency-Key` on every live create: a create that timed out and is > repeated without one makes a second store, and the second store starts a second > plan. > Sending `external_id` as well lets you find the store with > `GET /v1/stores?external_id=` when nobody retried. ### When the first charge cannot be paid A store whose first charge your balance and card cannot cover is still created, and the create still answers `201` with the store. It has no plan yet: its plan reads `awaiting_payment`, and every delivery it asks for is refused with `402 plan_required` until the month is paid. Nothing is past due, because nothing has been used. Listo charges it by itself the moment your live balance or your card covers it, as soon as you top up or save a card, and from then on the store can request couriers. You are told once that the store is waiting (see [what Listo tells you](#what-listo-tells-you)), and the price it will be charged is already fixed: it is the one your store took when it was created. ### When a charge fails A renewal your balance or card cannot pay leaves a store that was already running `past_due`, and every delivery it asks for is refused with `402 plan_required` until the month is paid. Listo tries the charge again as soon as you top up your live balance or save a card, and every day until it goes through. You are told when the charge fails, and three days before a renewal your balance cannot cover (see [what Listo tells you](#what-listo-tells-you)). ## Reading `plan` on a store Every store object carries `plan`: the create response, `GET /v1/stores/{id}`, every row of `GET /v1/stores`, the update response, and the store object a `store.updated` event carries. ```json theme={null} { "id": "st_4bR8kM2wQ7xT1nV5cZ9pLdYe", "access_tier": "api_only", "billing": "partner", "test": false, "plan": { "status": "active", "price_cents": 199000, "currency": "MXN", "interval": "month", "current_period_ends_on": "2026-10-06", "next_charge_on": "2026-10-07", "canceled_at": null, "ends_on": null, "paid_by": "partner", "pending_paid_by": null, "pending_paid_by_on": null, "courtesy": false } } ``` `plan` is null when the store needs no plan: a test store, or a live store created before Plan Listo existed, which keeps requesting couriers without one. If your agreement has each restaurant pay its own plan, `plan` is also null on a store whose restaurant has not bought one yet. When `plan` is an object, every key in it is always present, and the ones that do not apply are `null`. | Field | What it is | | - | - | | `status` | Where the plan stands. The next table. | | `price_cents` | What one month of this store's plan costs you, before IVA: your price, even while a connected restaurant is still paying its own plan. The charge is this plus IVA. | | `currency` | Always `"MXN"`. | | `interval` | How often this plan is charged: `"month"` for a plan you pay. On a plan the restaurant pays, the restaurant's own interval, `"month"` or `"year"`. | | `current_period_ends_on` | The last day of the current period, as a date: already paid unless `status` is `past_due`. | | `next_charge_on` | The day you are charged next: the next renewal, or, while a connected restaurant is still paying its own plan, your first charge. `null` once the plan is ending or has ended, because nothing more will be charged. `null` while the plan is `past_due` too, because the month owed has no date: it is charged the moment your balance or saved card allows, and retried every day until it is paid. `null` while `courtesy` is `true`, too. | | `canceled_at` | When you canceled the plan, as a timestamp. `null` otherwise. | | `ends_on` | The day the plan stops serving the store, which is the day after the last day paid, or the day you canceled a plan whose charge was pending. From that day its deliveries are refused. `null` unless the plan is ending or has ended. | | `paid_by` | Who pays this plan: `"partner"`, which is you, or `"store"`, the restaurant. | | `pending_paid_by` | Who will pay it from `pending_paid_by_on`, when that is about to change. `"partner"`, `"store"` or `null`. | | `pending_paid_by_on` | The date that change lands, or `null`. | | `courtesy` | `courtesy` is true while Listo waives this store's plan: nothing is charged and `next_charge_on` is null. | | `status` | What it means | Couriers | | - | - | - | | `active` | Paid up, and renews on `next_charge_on`. | yes | | `awaiting_payment` | The store's first month has not been paid: your balance and card could not cover it. It has no plan yet, `price_cents` is the price it will be charged before IVA (the amount needed to pay is that plus IVA), and the dates are `null`. Listo charges it as soon as you top up or save a card. | no, `plan_required` | | `past_due` | The month that is running has not been paid. Listo retries as soon as you top up or save a card, and every day. | no, `plan_required` | | `canceling` | Canceled by you. Served up to `ends_on`, and nothing more is charged. | yes, until the day before `ends_on` | | `canceled` | Ended. Nothing is charged, and it can be restarted. | no, `plan_required` | `paid_by` is `"store"` while a restaurant you connected is still paying its own plan: `pending_paid_by` is then `"partner"` and `pending_paid_by_on` is the date of its next renewal, the day the plan becomes yours and your first charge. On every other store both are `null`. If your agreement has each restaurant pay its own plan, `paid_by` is `"store"` for good and `price_cents` and `interval` are the price and the billing interval the restaurant pays. The one exception is a plan you were already paying on the day your agreement changed: it stays `paid_by: "partner"` until its next renewal, with `pending_paid_by: "store"` and `pending_paid_by_on` the day it passes to the restaurant, and `next_charge_on` is `null` because you are not charged again. `paid_by` and `billing` answer different questions, and neither can be read off the other. `billing` says whose balance pays the store's **deliveries**, and follows `access_tier`. `paid_by` says who pays its **plan**, which is you on every tier. A `full` store reads `billing: "store"` and `paid_by: "partner"`. A change to a store's plan sends a `store.updated` event carrying the whole store object, `plan` included: a plan that starts, a monthly renewal, a charge that fails or goes through, a cancellation, its undo, a plan that ends, a restart, a change of your price, and a plan moving to you. One act sends one event, carrying the state the plan ended in: a new store whose first charge cannot be paid sends a single event reading `awaiting_payment`, never an `active` before it. Changes that land close together can arrive as one event carrying the latest state, so read the `plan` each event carries rather than counting events. See [webhooks](https://docs.listo.delivery/en/guides/webhooks.md). When a restaurant connects, its `store.connected` comes first and shows the plan as it stood when the owner approved; the `store.updated` for the plan passing to you follows it. ## When a quote or a delivery is refused A live store without a paid-up plan answers `402 plan_required` on [`POST /v1/quotes`](https://docs.listo.delivery/api-reference/quotes/price-a-delivery), on [`POST /v1/deliveries`](https://docs.listo.delivery/api-reference/deliveries/create-a-delivery) and on [`POST /v1/deliveries/{id}/retries`](https://docs.listo.delivery/api-reference/deliveries/retry-a-failed-dispatch). The quote refuses too, because it would promise a price for a delivery the create would then refuse. Nothing was created, nothing was dispatched, and nothing was taken from your balance. ```json theme={null} { "error": { "code": "plan_required", "message": "This store's plan charge is pending.", "param": null, "retryable": false } } ``` It has five reasons, and `error.message` names the one it is: | Reason | What to do | | - | - | | The store has no active plan. | Restart it (below). | | The store's plan charge is pending. | Top up your live balance or save a card: the charge is tried again at once. | | The store's plan ended on a date the message gives. | Restart it (below). | | The store cannot request couriers right now. | Contact Listo. | | The store has used all the courier deliveries its plan includes for this cycle. | Wait for the renewal day the message gives: the count starts again with the new cycle. To lift the limit, contact Listo. | `retryable` is `false`: the identical request fails until somebody on your side pays, restarts the plan or hears back from Listo, or until the cycle renews. Branch on the code, surface it to whoever manages your Listo account with `error.message`, and tell the reasons apart by `error.message` alone. Do not read the store's `plan.status` for that: a store whose plan is `active` can still have used all the deliveries it includes, so `plan.status` stays `active` for that refusal. A card order created while the plan was paid up still dispatches when your customer pays, even if the plan lapsed in between: the order passed the check when it was created. ## Ending a store's plan [`POST /v1/stores/{id}/plan_cancellation`](https://docs.listo.delivery/api-reference/stores/cancel-a-stores-plan) cancels a store's plan, which the dashboard calls *Dar de baja*. It takes no body. The plan ends at the end of the month you already paid, with no refund, and the store keeps requesting couriers until then. It answers `200` with the store, whose plan now reads `canceling`, with `canceled_at` and `ends_on` filled in and `next_charge_on` at `null`. A plan whose charge is pending (`past_due`) has no paid month left to run out, and the store is already without couriers, so it ends the day you cancel it: the store answers with its plan `canceled` and that day in `ends_on`. From `ends_on` the plan is `canceled` and deliveries are refused with `plan_required`: a plan paid through 6 October reads `ends_on: "2026-10-07"` and stops serving that day. Nothing else goes away: the store keeps its id, its delivery history, its balance if it owns one, and its invoices, and nothing more is charged for it. `Idempotency-Key` is required, as it is on a delivery create. Repeating the call with the same key answers with the original response, so a cancellation that timed out can be sent again safely. `409 not_cancellable` means there is no plan to cancel: the store is already `canceling`, its plan has ended, or it needs no plan at all. ### Changing your mind [`DELETE /v1/stores/{id}/plan_cancellation`](https://docs.listo.delivery/api-reference/stores/undo-a-stores-plan-cancellation) undoes a cancellation before `ends_on`. The plan goes back to `active` and renews on the date it would have, as if you had never canceled it. It answers `200` with the store. It is safe to repeat. On a store whose plan is running with no cancellation to undo, it changes nothing and answers `200` with the store as it is. Once the plan has ended it is too late to undo, and the answer is `409 plan_ended`, whose message gives the date the cancellation took effect: restart the plan with `POST /v1/stores/{id}/plan` instead. A connected restaurant that is still paying its own plan decides its own cancellation until the plan moves to you. In that window a cancellation of its plan answers `409 not_cancellable`, and so does an undo of a cancellation the restaurant gave. ## Restarting an ended plan [`POST /v1/stores/{id}/plan`](https://docs.listo.delivery/api-reference/stores/reactivate-a-stores-plan) restarts the plan of a store whose plan is `canceled`. It takes no body. It charges a new month right away, from the same balance or card any other charge would use, and from then on the plan renews every month on the day of the month you restarted it. It answers `200` with the store, its plan `active`. `Idempotency-Key` is required here too. A restart that timed out and is repeated with the same key answers with the original response rather than charging a second month. | HTTP | `code` | What happened | | - | - | - | | 402 | `insufficient_balance` | Neither your balance nor your card could pay the month. Nothing changed: nothing was charged and the store stays ended. Top up or save a card and call again. | | 409 | `charge_in_progress` | A card charge for this store's plan is still with the bank. Nothing new was charged. `retryable` is `true`: read the store again in a few minutes, or repeat the call. | | 409 | `not_reactivatable` | The plan has not ended. A `canceling` store is undone with `DELETE /v1/stores/{id}/plan_cancellation`, and a `past_due` one starts again when its charge goes through. | All three plan endpoints answer `404 not_found` to a test key, because a test store has no plan to end or restart. ## A restaurant that already pays its own plan A restaurant that runs on Listo with an account of its own, and [connects to you](https://docs.listo.delivery/en/guides/connect-existing-account.md), may already be paying its own Plan Listo. If it has paid its current month, it goes on paying until its next renewal, and from that renewal its plan is charged to you. A restaurant that prepaid a year moves at the end of that year. Nothing is charged twice, there is no gap between the two, and nothing is prorated. The months it paid before that day are its own: they are invoiced to the restaurant, and never touch your balance, your invoices or your RFC. So is anything it still owed Listo for its own plan when it connected: Listo collects that from the restaurant, you are never told about it, and it never stops the couriers you pay for. Until that day the store reads `paid_by: "store"`, with `pending_paid_by: "partner"` and the date in `pending_paid_by_on`. `next_charge_on` is already your first charge and `price_cents` already your price, so the block always describes what you will pay. The `store.connected` event for the store shows the plan as it stood when the owner approved, the restaurant's own; a `store.updated` follows within moments with the block as above, and another arrives when the plan moves, the day it passes to you included. If the restaurant cancels its own plan before that day, its cancellation wins: the plan runs to the end of the time the restaurant already paid for and ends there, and it is never charged to you. The block then reads `status: "canceling"` with `paid_by: "store"` and no `pending_paid_by`, and your dashboard says the business canceled its plan and when it ends. You cannot undo the restaurant's cancellation, and there is nothing to reactivate until the plan has ended. From then on the store is an ended store like any other, and reactivating it starts your own plan that day. If the restaurant takes its cancellation back while its plan is still running, the move to you is back on, for the same renewal, and you are told again. A connected restaurant with no live plan of its own starts one the day it connects, and that first month is charged to you that day, exactly as for a store you create. A connected restaurant whose current month is unpaid when it connects does not wait for a renewal either: the plan passes to you that day, the month it had not paid is voided, so nobody is charged for it, and one full month is charged to you that day, exactly as for a store you create. Whatever it owed Listo for earlier months stays its own, as above. ## What Listo tells you Every email goes to every user on your partner account. The same moments reach you on WhatsApp when you set the number for charge notices on **Planes y facturación**: one number for the account, optional. * A store's plan started and its first month was charged. * A store's first month could not be covered by your balance or card, so the store is waiting and has no couriers until it is charged. Once per store. * The stores that renewed today: one email a day, with their invoices. * A charge failed. Once, when it fails: the daily retries after it are silent. * A renewal is three days away and your balance does not cover it. * You canceled a store's plan, with the day it ends. * Your agreed price changed, and from when. * A restaurant you connected is moving its plan to you, and the date. * A restaurant you connected canceled its own plan before it moved to you, so it does not move to you, and the day it ends. A store with a console owner hears from Listo too, because that owner runs the store: when its couriers stop because your charge is pending, when you cancel its plan, and when its plan moves to you. Each of those messages tells the owner to talk to you, and none of them shows what you pay. ## Invoices Each paid charge is invoiced with a CFDI to the fiscal data in **Datos de factura** on **Planes y facturación**. The invoice is emailed to every user on your account, and to the invoice address in **Datos de factura** when you set one, and it is listed on that page as PDF and XML, one row per charge and store. Only the months you pay are invoiced to you: a month a connected restaurant paid before its plan moved to you is invoiced to the restaurant. A charge paid before your fiscal data is in is invoiced as soon as you fill it in, and that invoice arrives in an email of its own. Fill it in before you create your first live store, so the first invoice comes with the first charge. ## Where each restaurant pays its own plan Some partners' agreements with Listo have each restaurant pay its own Plan Listo instead of the partner. Listo sets this on your account; it is not something the API or the dashboard changes. When it is set on yours: * You are never charged for a new store-paid period, and none of the charge emails or WhatsApps above reach you for one. Your balance and your card are not used for new plan periods. The change is forward only: a month already billed to you stays yours to pay, a plan you were already paying runs to the end of the period you paid and passes to the restaurant at its next renewal (`pending_paid_by: "store"`, with the date in `pending_paid_by_on`), and nothing is refunded or waived. * A store you create in live mode starts with no plan, so its `plan` is `null`. Before the restaurant can buy Plan Listo, the store must have `wallet` or `full` access and its owner must be invited to sign in: the restaurant buys the plan from its own console, in **Ajustes > Plan**, and pays from its own balance or card like any restaurant on Listo. A live store with `api_only` access has no console, so nobody could buy its plan: creating one, or moving a live store to `api_only`, is refused with `validation_failed` and `param: "access_tier"`, and Listo does not switch your account to this agreement while you hold one. Once the restaurant has bought it, `plan` is an object with `paid_by: "store"` and the price and `interval` (`"month"` or `"year"`) the restaurant pays. * Until a restaurant has a paid plan, its quotes and deliveries are refused with `402 plan_required`, as for any live store without a paid-up plan. There is no trial for these stores: test mode is where you rehearse. * A store that connects to you through [connect an existing account](https://docs.listo.delivery/en/guides/connect-existing-account.md) keeps paying its own plan, and nothing moves to you. * `POST /v1/stores/{id}/plan` does not restart such a plan, because it is not yours to pay: the restaurant does that from its console. ## In test mode None of this happens with a test key. Test stores carry `plan: null`, nothing is charged, no quote or delivery is refused with `plan_required`, and the three plan endpoints answer `404 not_found`. Test mode is where you rehearse everything else; the first plan you see is on your first live store. See [test mode](https://docs.listo.delivery/en/concepts/test-mode.md). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.