Merchants and connections

You can only access a merchant’s data after the merchant approves it. That approval is a connection.

What a connection contains

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

• scopes: what the merchant granted. This is at most what Loops approved for your application, and often less.
• location_ids: the branches you may access. Anything else returns 404.
• include_future_locations: whether branches the merchant adds later are shared automatically.
• external_ref: your identifier for this merchant, so you can match the connection to the account in your system.

Get the current connection at any time with GET /v1/connection.

How merchants connect

During the developer preview:

1. Send Loops the merchant’s name and your reference for them.
2. The merchant signs a consent form choosing branches and data.
3. Loops creates the connection.
4. You receive connection.created, with the merchant ID and your reference.

Coming next: a self-serve link. You create a link from your system; the merchant signs in to Loops, reviews your request, chooses branches and approves. See What’s coming.

When a merchant changes their mind

Event	What it means	What to do
connection.updated	Scopes or locations changed	Fetch GET /v1/connection and adjust what you sync
connection.revoked	Access withdrawn	Stop calling for this merchant. Further calls return connection_not_active.

IDs you will see

Prefix	What
mer_	Merchant
brd_	Brand
loc_	Location (branch or store)
chc_	Channel connection
con_	Connection
ord_	Order
evt_	Event

IDs are opaque strings. Store them as given, and don’t parse them.