Several shops

​

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.

​

Narrow a call with shop_id

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"

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(', ')}`);

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'])}")

{
  "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"] }
    ]
  }
}

​

Freshness across shops

• 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.

​

When an answer needs one shop

​

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.
• 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