Skip to main content
POST
Create a store

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.

Headers

​
Idempotency-Key
string

Optional. Send one to make a retry safe: generate a NEW key for each logical call (a UUID is a good one), at most 255 characters, and send the SAME key when you retry that call after a timeout or a dropped connection. The same key with the same body returns the ORIGINAL response, status code included, instead of doing the work again, for 24 hours. The same key with a different body is refused with 409 idempotency_conflict, and so is a retry that arrives while the first request is still being processed (try again shortly). Without the header nothing is remembered and a retry is a new request. A key belongs to your account and to the mode of the API key that sent it (live and test keys never meet), so the same text from two accounts, or from a live and a test key, is two different keys.

Body

application/json

The pickup location to create.

​
name
string
required
​
phone
string
required

A phone that resolves to an E.164 number.

​
street
string
required

The full street address, in one string.

​
apt_unit
string
​
lat
number<double>

Latitude. Send it together with lng, or neither.

Required range: -90 <= x <= 90
​
lng
number<double>

Longitude. Send it together with lat, or neither.

Required range: -180 <= x <= 180
​
pickup_notes
string

Instructions for the courier at the store, up to 280 characters.

Maximum string length: 280
​
timezone
string

An IANA time zone name.

​
default_business_fee_share
integer

The percent of the delivery fee the store pays by default.

Required range: 0 <= x <= 100
​
access_tier
enum<string>

What the store gets besides the API.

Available options:
api_only,
wallet,
full
​
markup_cents
integer

Your markup on each delivery, in centavos, up to 1000000.

Required range: 0 <= x <= 1000000
​
external_id
string

Your own reference for this location.

Maximum string length: 255
​
owner_email
string

The restaurant owner to invite, for a store with a console.

Response

Created.

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

​
id
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"

​
default_business_fee_share
integer
required

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.