ShopEazydevelopers
API referenceMerchant API BetaSession

The businesses the person belongs to, with their stores

Beta
Credentials
  • OAuth access token
Scopes
store:read
GET
/v1/merchant/workspaces

Each business with the person's role in it, its plan, how many stores it has and may have, and its stores (the same summaries as getSession). A client picks the store to work on from here and puts its id in the path of every call: switching is client state, so there is nothing to call for it.

A connected AI app sees only the business, and the stores, it was granted; storeCount is still the business's real count, which is what the plan's cap counts. A person with no business yet gets an empty list.

Access: OAuth scope store:read; not write-gated.

Paged: { items, nextCursor }, limit (default 50, at most 100) and an opaque cursor.

Authorization

merchantOAuth store:read
headerAuthorizationBearer <token>

OAuth 2.1 (authorization code + PKCE S256, public clients, dynamic registration) for connected AI apps. Effective power is scopes granted AND the person's role today AND the plan. orders:refund, billing:write and team:write are opt-in on the consent screen. Write implies read for marketing:read and messages:read, so a grant holding marketing:write passes a marketing:read check, and messages:send passes messages:read.

Scope: store:read

Query Parameters

cursor?string

The nextCursor of the previous page, unchanged. A cursor that is not one we gave you is 400 bad_request.

limit?integer

Page size: default 50, at most 100 (more is 100; a missing or unusable value is 50).

Range1 <= value <= 100
Default50

Response Body

OK

application/json
  1. response
data*
Example Request
curl -X GET 'https://api.shopeazy.co/v1/merchant/workspaces' \  -H 'Authorization: Bearer <access_token>'
Example Response
{  "data": {    "items": [      {        "id": "EjblZNtyBUWK7jGqf7ST",        "name": "Jabu's Plant Shop",        "role": "owner",        "plan": {          "id": "growth",          "name": "Growth"        },        "storeCount": 1,        "maxStores": 3,        "canAddStore": true,        "stores": [          {            "id": "w82oaN7OkGK7BykWs2Ag",            "workspaceId": "EjblZNtyBUWK7jGqf7ST",            "name": "Jabu's Plant Shop",            "slug": "jabus-plant-shop",            "logoUrl": null,            "currency": "ZAR",            "role": "owner",            "kitTypes": [              "physical",              "service",              "ticketing"            ]          }        ]      }    ],    "nextCursor": null  }}

Who is signed in, and every store they can act on GET

A person with no ShopEazy profile yet gets `stores: []` and `defaultStoreId: null` (they go to onboarding). Access: OAuth scope `store:read`; not write-gated.

The merchant agreement, fee schedule and prohibited uses GET

Public: the route never reads the token today, and the terms are published on shopeazy.co anyway. Access: public, no token; not write-gated.