Merchants, brands and locations

How a business is organized

Merchant (mer_)                      the business
 ├── Business profile                legal details and documents, reviewed by Loops
 └── Brand (brd_)                    what customers see on delivery apps; has one menu
      └── Location (loc_)            a branch, with address and opening hours
           └── Channel connection    the branch on one delivery app (chc_)

• A merchant can have several brands, and a brand several locations.
• Every location belongs to exactly one brand, and uses that brand’s menu.
• Channel connections are set up by Loops, not through the API. You can read them, and you get channel_connection.status_changed when one goes live.

Two ways to get access to a merchant

You create the merchant

This is the usual case for a POS: the restaurant is your customer, and you set it up on Loops.

1. POST /v1/merchants creates the business and connects it to your application straight away.
2. Loops emails the owner an invitation to sign in to Loops. You never handle their password.
3. You can add brands, locations and menus immediately.
4. You fill in the business profile and submit it for review. Locations go live on delivery apps only after it is approved.

If the owner’s email or phone already belongs to a Loops account, you get 409 merchant_exists. The restaurant already uses Loops; follow the next path instead.

The merchant already uses Loops

1. Email partners@loops.sa with the merchant’s name and your own reference for them.
2. The merchant confirms in writing which locations and data you may access.
3. Loops creates the connection, and you receive connection.created with the merchant ID and your reference.

The connection

A connection records what your application may do for a merchant (con_…). Read it with GET /v1/connection:

{
  "id": "con_4Tz8Yp1W",
  "merchant_id": "mer_7Hq2Lw8Z",
  "external_ref": "CUST-10021",
  "status": "active",
  "scopes": ["merchant:write", "locations:write", "catalog:write", "orders:read", "events:read"],
  "location_ids": ["loc_2Xf9K", "loc_8Pn4R"],
  "include_future_locations": true,
  "created_at": "2026-10-01T09:12:44Z"
}

• scopes: what you may do. For merchants you created, every scope approved for your application.
• location_ids: the locations you may access. Anything else returns 404.
• include_future_locations: always true for merchants you created.
• external_ref: your identifier for this merchant.

If the merchant withdraws access, you receive connection.revoked. Stop calling for that merchant; further calls return connection_not_active.

IDs you will see

Prefix	What
mer_	Merchant
doc_	Business profile document
brd_	Brand
loc_	Location
chc_	Channel connection
con_	Connection
job_	Menu import or publish job
ord_	Order
evt_	Event

IDs are opaque strings. Store them as given, and don’t parse them. Menu items have no Loops IDs; they use your own external_ref values.