Exchange an approval for the store

curl --request POST \
  --url https://api.listo.delivery/v1/connections \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "code": "pcc_8vZ1nK5xQ3tR9bM7cW2sLdYe"
}
'

import requests

url = "https://api.listo.delivery/v1/connections"

payload = { "code": "pcc_8vZ1nK5xQ3tR9bM7cW2sLdYe" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({code: 'pcc_8vZ1nK5xQ3tR9bM7cW2sLdYe'})
};

fetch('https://api.listo.delivery/v1/connections', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.listo.delivery/v1/connections",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'code' => 'pcc_8vZ1nK5xQ3tR9bM7cW2sLdYe'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.listo.delivery/v1/connections"

	payload := strings.NewReader("{\n  \"code\": \"pcc_8vZ1nK5xQ3tR9bM7cW2sLdYe\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.listo.delivery/v1/connections")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"code\": \"pcc_8vZ1nK5xQ3tR9bM7cW2sLdYe\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.listo.delivery/v1/connections")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"code\": \"pcc_8vZ1nK5xQ3tR9bM7cW2sLdYe\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "st_4bR8kM2wQ7xT1nV5cZ9pLdYe",
  "external_id": null,
  "name": "La Taqueria del Centro",
  "phone": "+523312345678",
  "street": "Av. Juan Palomar y Arias 765",
  "apt_unit": null,
  "lat": 20.691145,
  "lng": -103.426885,
  "pickup_notes": null,
  "timezone": "America/Mexico_City",
  "default_business_fee_share": 0,
  "access_tier": "full",
  "markup_cents": 0,
  "billing": "store",
  "test": false,
  "created_at": "2026-07-30T18:30:00Z",
  "default_fee_split_mode": "percent",
  "default_fee_split_amount_cents": null,
  "plan": null
}

{
  "error": {
    "code": "code_expired",
    "message": "That connection code has expired. The store was connected when the owner approved: read it from GET /v1/stores.",
    "param": null,
    "retryable": false,
    "doc_url": "https://docs.listo.delivery/en/errors/code_expired",
    "request_id": "0b1f6c9a-7e2d-4c53-9a41-5d8e3f2a6b10"
  }
}

{
  "error": {
    "code": "read_only_key",
    "message": "This API key is read-only. Use a key without the read-only setting to create, change or cancel anything.",
    "param": null,
    "retryable": false,
    "doc_url": "https://docs.listo.delivery/en/errors/read_only_key",
    "request_id": "0b1f6c9a-7e2d-4c53-9a41-5d8e3f2a6b10"
  }
}

{
  "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"
  }
}

Account connection

Exchange an approval for the store

Exchanges the code from an approved connect request for the store it connected. What comes back is an ordinary store object, identical to what POST /v1/stores returns, and every store endpoint works on it immediately.

The code is good for 24 hours and can be exchanged more than once: every exchange inside the window returns the same store. That is deliberate, so an exchange whose response you never received is a retry rather than a support thread. Past the window it is 400 code_expired, but the connection itself happened when the owner approved: the store is on GET /v1/stores and its store.connected was sent then, so read it from there. Do not start a new connect request for it; the account is already connected.

You do not have to wait for the browser to come back. A store.connected webhook carries the whole store object the moment the owner approves, which is your recovery path when the owner closes the tab before the redirect lands.

POST

connections

Exchange an approval for the store

curl --request POST \
  --url https://api.listo.delivery/v1/connections \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "code": "pcc_8vZ1nK5xQ3tR9bM7cW2sLdYe"
}
'

import requests

url = "https://api.listo.delivery/v1/connections"

payload = { "code": "pcc_8vZ1nK5xQ3tR9bM7cW2sLdYe" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({code: 'pcc_8vZ1nK5xQ3tR9bM7cW2sLdYe'})
};

fetch('https://api.listo.delivery/v1/connections', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.listo.delivery/v1/connections",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'code' => 'pcc_8vZ1nK5xQ3tR9bM7cW2sLdYe'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.listo.delivery/v1/connections"

	payload := strings.NewReader("{\n  \"code\": \"pcc_8vZ1nK5xQ3tR9bM7cW2sLdYe\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.listo.delivery/v1/connections")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"code\": \"pcc_8vZ1nK5xQ3tR9bM7cW2sLdYe\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.listo.delivery/v1/connections")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"code\": \"pcc_8vZ1nK5xQ3tR9bM7cW2sLdYe\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "st_4bR8kM2wQ7xT1nV5cZ9pLdYe",
  "external_id": null,
  "name": "La Taqueria del Centro",
  "phone": "+523312345678",
  "street": "Av. Juan Palomar y Arias 765",
  "apt_unit": null,
  "lat": 20.691145,
  "lng": -103.426885,
  "pickup_notes": null,
  "timezone": "America/Mexico_City",
  "default_business_fee_share": 0,
  "access_tier": "full",
  "markup_cents": 0,
  "billing": "store",
  "test": false,
  "created_at": "2026-07-30T18:30:00Z",
  "default_fee_split_mode": "percent",
  "default_fee_split_amount_cents": null,
  "plan": null
}

{
  "error": {
    "code": "code_expired",
    "message": "That connection code has expired. The store was connected when the owner approved: read it from GET /v1/stores.",
    "param": null,
    "retryable": false,
    "doc_url": "https://docs.listo.delivery/en/errors/code_expired",
    "request_id": "0b1f6c9a-7e2d-4c53-9a41-5d8e3f2a6b10"
  }
}

{
  "error": {
    "code": "read_only_key",
    "message": "This API key is read-only. Use a key without the read-only setting to create, change or cancel anything.",
    "param": null,
    "retryable": false,
    "doc_url": "https://docs.listo.delivery/en/errors/read_only_key",
    "request_id": "0b1f6c9a-7e2d-4c53-9a41-5d8e3f2a6b10"
  }
}

{
  "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"
  }
}

Authorizations

Authorization

string

header

required

Your API key, sent as Authorization: Bearer <key>. Live and test keys are separate; the key you send decides which world the call acts in. To try calls, use a test key (it starts with lst_test_): no real courier is sent and no real money moves, but webhooks fire and the dropoff.phone you give can receive WhatsApp messages, so use your own number. A live key (it starts with lst_live_) books and charges real deliveries.

Body

application/json

The one-time code from an approved connect request.

code

string

required

The pcc_ code that arrived at your redirect_uri.

Response

Created.

A pickup location. Card readiness is deliberately NOT a field here: it is its own endpoint, with its own outstanding-requirements detail.

string

required

The store id, st_ prefixed.

Example:

"st_4bR8kM2wQ7xT1nV5cZ9pLdYe"

external_id

string | null

required

Your own reference for this location, if you sent one. Unique per key world, and filterable on the list, so you can reconcile against your own store book without storing our ids.

Example:

"pos-store-41"

name

string

required

The name you gave the store; for a restaurant that connected an account with several branches, the business and the branch, the way its own customers read it (Tortería La Mera Mera, Zapopan). A branch whose own name already begins with the business's name, such as Tortería La Mera Mera Centro, is published as it is. When you send a name, a value that begins with the store's business name and a comma is read as that business plus the branch, so sending back the name you read changes nothing.

phone

string

required

E.164, normalized on the way in.

street

string

required

apt_unit

string | null

required

lat

number<double> | null

required

lng

number<double> | null

required

pickup_notes

string | null

required

Standing instructions for the courier collecting here.

timezone

string

required

The IANA zone the store keeps its hours in, normalized to one spelling per zone. Derived from the store's coordinates, and re-derived whenever the store's position moves. A zone you send yourself is used only when the position cannot answer (a store with no coordinates, or a position no zone claims), and one that disagrees with the position is neither stored nor treated as an error.

Example:

"America/Mexico_City"

The share of the delivery fee this store covers by default, as a percentage. The rest is charged to the customer. In force only when default_fee_split_mode is percent; in either amount mode this is the percentage the store keeps for when it goes back to one.

Required range: 0 <= x <= 100

default_fee_split_mode

enum<string>

required

Which shape this store's default split has, and therefore which of the two fields above and below is in force. percent splits the fee by default_business_fee_share; business_amount means the store covers up to default_fee_split_amount_cents of it and the customer pays the rest; customer_amount is the mirror, the customer paying up to that amount and the store covering the rest.

Read-only. It is set by the restaurant in its own Listo console, and sending default_business_fee_share on a create or an update moves the store back to percent.

Available options:

percent,

business_amount,

customer_amount

default_fee_split_amount_cents

integer | null

required

The amount the two amount modes divide the fee by, in cents. Null in percent mode, and never null in either amount mode. Read-only.

Required range: x >= 0

access_tier

enum<string>

required

How much of Listo the store itself uses. An api_only store's deliveries spend your balance, and a wallet or full store's spend its own; billing says which. Writable on create and update, and always api_only on a test store. A live store of an account whose restaurants pay their own Plan Listo cannot be api_only: it has no console to buy a plan from, so a create or an update that asks for it is refused with 422 validation_failed and param: "access_tier".

Available options:

api_only,

wallet,

full

markup_cents

integer

required

Your own markup on every delivery of this store, in cents. It is added to the delivery fee, split with the customer like the rest of the fee, and credited to your balance when the delivery is delivered. Writable on create and update.

Required range: x >= 0

billing

enum<string>

required

Whose balance pays this store's deliveries, read off access_tier so you never have to derive it: partner is yours, store is the store's own. Read-only. It is not who pays the store's plan, which is plan.paid_by.

Available options:

partner,

store

test

boolean

required

created_at

string<date-time>

required

plan

object | null

required

The store's Plan Listo, or 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. It is also null when the store pays its own plan (every store of an account whose stores pay their own Plan Listo) and the restaurant has not bought one yet: the restaurant buys it in its own console, and there is nothing for you to pay or to reactivate. It is also null for a store of a partner on pricing with no Plan Listo, which needs no plan. When it is an object every key is present, and the ones that do not apply are null. See Plan and billing.

Show child attributes

Get started

Guides

Errors

Reference

Concepts

Changelog

Legal

Exchange an approval for the store

Authorizations

Body

Response