# Stores — Eto API

> The Etsy stores connected to your Eto account.

Base URL `https://eto.tools/api/v1/`. Every request carries the `X-Eto-API-Key` header. Part of the [Eto API reference](https://eto.tools/dev/docs/).

## Endpoints in this category

- [GET /api/v1/stores](https://eto.tools/dev/docs/stores/stores-list.md): List connected stores
- [GET /api/v1/stores/{shop_id}](https://eto.tools/dev/docs/stores/store-detail.md): Get a connected store

## GET /api/v1/stores

List connected stores

- Operation ID: `stores_list`
- Slug: `stores-list`
- Category: Stores
- Authentication: API key only. Reads or writes data Eto holds for your own account.
- HTML: https://eto.tools/dev/docs/#ep-stores-list
- Markdown: https://eto.tools/dev/docs/stores/stores-list.md

List every Etsy store connected to your Eto account, with shop_id, name and basic status. Start here: the shop_id values are what every shop-scoped endpoint needs. `token_valid` false means the store is connected but its Etsy authorisation has lapsed, so shop-scoped calls will answer STORE_TOKEN_EXPIRED until it is reconnected. Verified against developer_api/views_stores.py.

### Parameters

None. Send the request with only the API key header.

### Request

```bash
curl -X GET "https://eto.tools/api/v1/stores" \
  -H "X-Eto-API-Key: eto_your_key"
```

```python
import requests

url = "https://eto.tools/api/v1/stores"
headers = {"X-Eto-API-Key": "eto_your_key"}

response = requests.get(url, headers=headers, timeout=120)
response.raise_for_status()
print(response.json())
```

```javascript
const url = "https://eto.tools/api/v1/stores";

const response = await fetch(url, {
  method: "GET",
  headers: {
    "X-Eto-API-Key": "eto_your_key",
  },
});
if (!response.ok) throw new Error(`Eto API ${response.status}`);
const data = await response.json();
```

### Response

```json
{
  "stores": [
    {
      "shop_id": "12345678",
      "shop_name": "MyShop",
      "is_connected": true,
      "token_valid": true,
      "connected_at": "2026-04-19T14:30:00+00:00"
    }
  ]
}
```

### Errors

Failures answer with the shared error body described in the Errors section: `{"error": {"code", "status", "message", "hint", "docs"}}`. Branch on `code`, not on the message.


## GET /api/v1/stores/{shop_id}

Get a connected store

- Operation ID: `store_detail`
- Slug: `store-detail`
- Category: Stores
- Authentication: API key only. Reads or writes data Eto holds for your own account.
- HTML: https://eto.tools/dev/docs/#ep-store-detail
- Markdown: https://eto.tools/dev/docs/stores/store-detail.md

Get details for a single connected store you own.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `shop_id` | path | `integer` | yes | Eto/Etsy shop id from /api/v1/stores |

### Request

```bash
curl -X GET "https://eto.tools/api/v1/stores/12345678" \
  -H "X-Eto-API-Key: eto_your_key"
```

```python
import requests

url = "https://eto.tools/api/v1/stores/12345678"
headers = {"X-Eto-API-Key": "eto_your_key"}

response = requests.get(url, headers=headers, timeout=120)
response.raise_for_status()
print(response.json())
```

```javascript
const url = "https://eto.tools/api/v1/stores/12345678";

const response = await fetch(url, {
  method: "GET",
  headers: {
    "X-Eto-API-Key": "eto_your_key",
  },
});
if (!response.ok) throw new Error(`Eto API ${response.status}`);
const data = await response.json();
```

### Response

`application/json`. This endpoint has no worked response example in the registry yet; the [HTML reference](https://eto.tools/dev/docs/#ep-store-detail) shows the fields it returns.

### Errors

Failures answer with the shared error body described in the Errors section: `{"error": {"code", "status", "message", "hint", "docs"}}`. Branch on `code`, not on the message.