> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alura.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Several shops

> Every Your shop read covers all your connected shops; narrow it with shop_id

Most sellers have one shop, so the Your shop API never makes you look up a shop ID first. Every read covers every shop connected to the workspace. If you have several, you narrow a call with `shop_id`.

## Every shop by default

* **Lists and searches** (listings, orders, reviews, customers, changes, syncs) return items from every connected shop, unless `shop_id` narrows them.
* **Stats** add up every connected shop, unless `shop_id` narrows them.
* **Every item carries its `shop_id`**, so you can tell the shops apart in one list.
* **IDs of listings, orders, reviews and customers are unique on Etsy**, so their paths take no shop ID: `GET /v1/workspace/listings/{id}` finds the listing in whichever of your shops holds it.

In an AI assistant, `list_my_shops` returns the shops and their IDs. Call it first. The shops can change between conversations, because the workspace can connect or remove a shop, and a grant can switch workspace.

## Narrow a call with `shop_id`

On REST, `shop_id` takes one shop or several, comma-separated or repeated: `?shop_id=22841907,30577120`. MCP tools take `shop_id` as a JSON array, such as `{"shop_id": ["22841907", "30577120"]}`, except `get_my_shop`, which always requires `shop_id`, one shop as a string, even when the workspace has one shop, and `start_my_sync`, which takes one shop as a string or none for every shop.

```bash cURL theme={null}
curl --fail-with-body -sS -G https://api.alura.io/v1/workspace/shops \
  -H "Authorization: Bearer $ALURA_API_KEY" \
  --data-urlencode "shop_id=22841907,30577120"
```

```typescript TypeScript theme={null}
interface Shops {
  data: { id: string; name: string | null; as_of: string | null }[];
  summary: { as_of: string | null; freshness: { shop_id: string; as_of: string | null }[]; notices: { code: string; shop_ids: string[] }[] };
}

const res = await fetch('https://api.alura.io/v1/workspace/shops?shop_id=22841907,30577120', {
  headers: { Authorization: `Bearer ${process.env.ALURA_API_KEY}` },
});
if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
const shops = (await res.json()) as Shops;

for (const shop of shops.data) console.log(`${shop.id} ${shop.name}: stored ${shop.as_of ?? 'never'}`);
// The page's as_of is its oldest shop's; freshness has each shop's.
console.log(`oldest: ${shops.summary.as_of ?? 'unknown'}`);
for (const notice of shops.summary.notices) console.log(`notice ${notice.code}: ${notice.shop_ids.join(', ')}`);
```

```python Python theme={null}
import json
import os
import urllib.request

request = urllib.request.Request(
    "https://api.alura.io/v1/workspace/shops?shop_id=22841907,30577120",
    headers={"Authorization": f"Bearer {os.environ['ALURA_API_KEY']}"},
)
with urllib.request.urlopen(request) as response:
    shops = json.load(response)

for shop in shops["data"]:
    print(f"{shop['id']} {shop['name']}: stored {shop['as_of'] or 'never'}")
# The page's as_of is its oldest shop's; freshness has each shop's.
print(f"oldest: {shops['summary']['as_of'] or 'unknown'}")
for notice in shops["summary"]["notices"]:
    print(f"notice {notice['code']}: {', '.join(notice['shop_ids'])}")
```

```json Response theme={null}
{
  "data": [
    { "id": "22841907", "name": "GiftMugStudio", "as_of": "2026-10-08T06:00:00.000Z" },
    { "id": "30577120", "name": "ClayAndName", "as_of": "2026-10-17T06:00:00.000Z" }
  ],
  "summary": {
    "as_of": "2026-10-08T06:00:00.000Z",
    "freshness": [
      { "shop_id": "22841907", "as_of": "2026-10-08T06:00:00.000Z" },
      { "shop_id": "30577120", "as_of": "2026-10-17T06:00:00.000Z" }
    ],
    "notices": [
      { "code": "stale_shops", "shop_ids": ["22841907"] },
      { "code": "sales_not_covered", "shop_ids": ["30577120"] }
    ]
  }
}
```

A shop ID that isn't connected to the workspace returns `404 not_found` for the whole call. Alura never drops the unknown ID and answers for the rest, and it never widens the call to other shops.

## Freshness across shops

Each shop is synced on its own, so the shops in one answer can be stored at different times. A list's `summary` says how fresh each one is:

* `as_of` is the oldest shop's time, so you never read the answer as newer than it is. It's `null` if any shop's time is unknown.
* `freshness` lists each shop's own `as_of`.
* `notices` name shops by ID: `stale_shops` for data more than 7 days old, `sales_not_covered` for shops whose sales Alura doesn't cover yet. See [Coverage](/guides/your-shop-coverage).

## When an answer needs one shop

An operation that acts on exactly one shop takes `shop_id`, and it's optional when the workspace has only one. With several shops, leaving it out returns `400 shop_id_required`, and its `shops` field lists each shop's `id` and `name` to choose from. The same rule applies on REST and MCP. Every read in this version covers several shops, so no read returns it.

## Shops in the same answer

* **Customers are merged across shops.** A buyer who ordered from two of your shops is one customer, with both shops in `shop_ids`, and their orders and spending added up. Only the shops you selected count. The name and location come from the shop of their latest order. Guest buyers, who checked out without an Etsy account, aren't customers.
* **Money in several currencies.** A listing's or customer's money stays in its own currency with a `usd` value. When a total mixes currencies, `amount` and `currency` are `null` and only `usd` is given.
* **Shop stats** report in one currency. Shops with different currencies are converted, and the response says so in `conversion`. Add `group_by=shop` for each shop's own totals in `by_shop`. See [Shop stats](/methodology/shop-stats#currency).
* **Sales sorts** leave out shops whose sales Alura doesn't cover for the period, and name them in `sales_not_covered`. The other shops are still ranked.

## Next steps

> **[Connect and sync](/guides/your-shop-connect-and-sync)**
>
> Connect a shop and start a sync.

> **[Coverage](/guides/your-shop-coverage)**
>
> Why a sales number can be null.

> **[Buyer data](/guides/your-shop-buyer-data)**
>
> Scopes, permissions and what reaches your AI client.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.