# Shops

> List, create and fetch a tenant's shops.

# Shops

`{idOrName}` in every route below accepts either the shop's ObjectId or its
exact name (case-insensitive) — URL-encode the name when it contains spaces
(`Shop%20Name`). Two shops sharing a name resolves to
`409 AMBIGUOUS_SHOP` with the candidate ids listed; use the id from then on.

| Method | Path | Permission | Purpose |
|---|---|---|---|
| GET | `/shops?page=&limit=` | `shops.read` | paginated list, newest first |
| POST | `/shops` | `shops.write` | create with the bare minimum |
| GET | `/shops/{idOrName}` | `shops.read` | one shop |

## Create a shop

`POST /shops` takes only `{ name, phone? }` — everything else (coordinates,
opening hours, pickup points, channels) is completed in the dashboard. The
response is `201` with a `setupUrl` that opens the shop's edit form directly,
and `setupRequired: ["location", "operatingHours"]` naming what is still
missing.

```bash
curl -s -X POST -H "Authorization: Bearer omk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"SHOP_NAME","phone":"+24177000000"}' \
  https://app.omni-manager.com/api/v1/shops
```

Fails `402 QUOTA_EXCEEDED` at the plan's shop limit, `409 SHOP_NAME_TAKEN` on
a duplicate name, and `409 TENANT_OWNER_MISSING` if the tenant has no owner
user on record (create it from the dashboard instead in that case).