# Store Management — Eto API

> Create and edit listings inside a shop you own.

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/POST /api/v1/shops/{shop_id}/listings](https://eto.tools/dev/docs/store-management/shop-listings.md): List or create shop listings
- [PATCH /api/v1/shops/{shop_id}/listings/{listing_id}](https://eto.tools/dev/docs/store-management/shop-listing-update.md): Update a listing
- [GET /api/v1/shops/{shop_id}/listings/active](https://eto.tools/dev/docs/store-management/shop-active-listings.md): Get active listings only
- [GET /api/v1/shops/{shop_id}/listings/featured](https://eto.tools/dev/docs/store-management/shop-featured-listings.md): Get featured listings
- [GET/POST/PUT /api/v1/shops/{shop_id}/listings/{listing_id}/translations/{language}](https://eto.tools/dev/docs/store-management/listing-translation.md): Manage listing translations

## GET · POST /api/v1/shops/{shop_id}/listings

List or create shop listings

- Operation ID: `shop_listings_get`
- Slug: `shop-listings`
- Category: Store Management
- Authentication: API key plus a connected store. Eto uses that store’s Etsy token, so the shop_id must belong to a store connected to your Eto account or the call answers 403 STORE_NOT_CONNECTED.
- HTML: https://eto.tools/dev/docs/#ep-shop-listings
- Markdown: https://eto.tools/dev/docs/store-management/shop-listings.md
- Operation IDs by method: `shop_listings_get` = GET, `shop_listings_post` = POST

GET: Retrieve your shop listings. POST: Create a new draft listing.

Proxied to the Etsy API at `/v3/application/shops/{shop_id}/listings`. Fields Etsy returns are passed through untouched.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `shop_id` | path | `integer` | yes | Your Etsy shop ID |
| `limit` | query | `integer` | no | Number of listings (max 100) Default: `25`. |
| `offset` | query | `integer` | no | Pagination offset Default: `0`. |
| `state` | query | `string` | no | Listing state: active, draft, inactive Default: `active`. |
| `sort_on` | query | `string` | no | Sort field Default: `created`. |
| `sort_order` | query | `string` | no | Sort direction Default: `desc`. |

### Request — GET

```bash
curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/shops/12345678/listings?limit=10&state=active"
```

```python
import requests

url = "https://eto.tools/api/v1/shops/12345678/listings?limit=10&state=active"
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/shops/12345678/listings?limit=10&state=active";

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

### Request — POST

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

```python
import requests

url = "https://eto.tools/api/v1/shops/12345678/listings"
headers = {"X-Eto-API-Key": "eto_your_key"}
params = {
    "limit": 25,
    "offset": 0
}

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

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

const response = await fetch(url, {
  method: "POST",
  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`, passed through from Etsy’s `/v3/application/shops/{shop_id}/listings` verbatim. The field-by-field data model is in the [v2 preview reference](https://eto.tools/eto-dev-api-v2/), which documents these same routes alongside the whole Etsy schema.

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

This endpoint can additionally return `STORE_NOT_CONNECTED` (403) when the shop is not linked to your account, and `STORE_TOKEN_EXPIRED` (503) when its Etsy authorisation has lapsed and needs reconnecting.


## PATCH /api/v1/shops/{shop_id}/listings/{listing_id}

Update a listing

- Operation ID: `shop_listing_update`
- Slug: `shop-listing-update`
- Category: Store Management
- Authentication: API key plus a connected store. Eto uses that store’s Etsy token, so the shop_id must belong to a store connected to your Eto account or the call answers 403 STORE_NOT_CONNECTED.
- HTML: https://eto.tools/dev/docs/#ep-shop-listing-update
- Markdown: https://eto.tools/dev/docs/store-management/shop-listing-update.md

Update properties of a listing you own.

Proxied to the Etsy API at `/v3/application/shops/{shop_id}/listings/{listing_id}`. Fields Etsy returns are passed through untouched.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `shop_id` | path | `integer` | yes | Your Etsy shop ID |
| `listing_id` | path | `integer` | yes | The listing ID to update |

### Request

```bash
curl -X PATCH -H "X-Eto-API-Key: eto_your_key" -H "Content-Type: application/json" -d '{"title": "Updated Title"}' "https://eto.tools/api/v1/shops/12345678/listings/1234567890"
```

```python
import requests

url = "https://eto.tools/api/v1/shops/12345678/listings/1234567890"
headers = {"X-Eto-API-Key": "eto_your_key"}
payload = {
    "title": "Updated Title"
}

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

```javascript
const url = "https://eto.tools/api/v1/shops/12345678/listings/1234567890";
const payload = {
  "title": "Updated Title"
};

const response = await fetch(url, {
  method: "PATCH",
  body: JSON.stringify(payload),
  headers: {
    "X-Eto-API-Key": "eto_your_key",
    "Content-Type": "application/json",
  },
});
if (!response.ok) throw new Error(`Eto API ${response.status}`);
const data = await response.json();
```

### Response

`application/json`, passed through from Etsy’s `/v3/application/shops/{shop_id}/listings/{listing_id}` verbatim. The field-by-field data model is in the [v2 preview reference](https://eto.tools/eto-dev-api-v2/), which documents these same routes alongside the whole Etsy schema.

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

This endpoint can additionally return `STORE_NOT_CONNECTED` (403) when the shop is not linked to your account, and `STORE_TOKEN_EXPIRED` (503) when its Etsy authorisation has lapsed and needs reconnecting.


## GET /api/v1/shops/{shop_id}/listings/active

Get active listings only

- Operation ID: `shop_active_listings`
- Slug: `shop-active-listings`
- Category: Store Management
- Authentication: API key plus a connected store. Eto uses that store’s Etsy token, so the shop_id must belong to a store connected to your Eto account or the call answers 403 STORE_NOT_CONNECTED.
- HTML: https://eto.tools/dev/docs/#ep-shop-active-listings
- Markdown: https://eto.tools/dev/docs/store-management/shop-active-listings.md

Get only active (live) listings for your shop. Etsy docs: "Active Listings By Shop".

Proxied to the Etsy API at `/v3/application/shops/{shop_id}/listings/active`. Fields Etsy returns are passed through untouched.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `shop_id` | path | `integer` | yes | Your Etsy shop ID |
| `limit` | query | `integer` | no | Number of results (max 100) Default: `25`. |
| `offset` | query | `integer` | no | Pagination offset Default: `0`. |

### Request

```bash
curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/shops/12345678/listings/active?limit=10"
```

```python
import requests

url = "https://eto.tools/api/v1/shops/12345678/listings/active?limit=10"
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/shops/12345678/listings/active?limit=10";

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`, passed through from Etsy’s `/v3/application/shops/{shop_id}/listings/active` verbatim. The field-by-field data model is in the [v2 preview reference](https://eto.tools/eto-dev-api-v2/), which documents these same routes alongside the whole Etsy schema.

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

This endpoint can additionally return `STORE_NOT_CONNECTED` (403) when the shop is not linked to your account, and `STORE_TOKEN_EXPIRED` (503) when its Etsy authorisation has lapsed and needs reconnecting.


## GET /api/v1/shops/{shop_id}/listings/featured

Get featured listings

- Operation ID: `shop_featured_listings`
- Slug: `shop-featured-listings`
- Category: Store Management
- Authentication: API key plus a connected store. Eto uses that store’s Etsy token, so the shop_id must belong to a store connected to your Eto account or the call answers 403 STORE_NOT_CONNECTED.
- HTML: https://eto.tools/dev/docs/#ep-shop-featured-listings
- Markdown: https://eto.tools/dev/docs/store-management/shop-featured-listings.md

Get listings featured on your shop's homepage. Etsy docs: "Featured Listings By Shop".

Proxied to the Etsy API at `/v3/application/shops/{shop_id}/listings/featured`. Fields Etsy returns are passed through untouched.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `shop_id` | path | `integer` | yes | Your Etsy shop ID |
| `limit` | query | `integer` | no | Number of results (max 100) Default: `25`. |
| `offset` | query | `integer` | no | Pagination offset Default: `0`. |

### Request

```bash
curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/shops/12345678/listings/featured?limit=5"
```

```python
import requests

url = "https://eto.tools/api/v1/shops/12345678/listings/featured?limit=5"
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/shops/12345678/listings/featured?limit=5";

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`, passed through from Etsy’s `/v3/application/shops/{shop_id}/listings/featured` verbatim. The field-by-field data model is in the [v2 preview reference](https://eto.tools/eto-dev-api-v2/), which documents these same routes alongside the whole Etsy schema.

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

This endpoint can additionally return `STORE_NOT_CONNECTED` (403) when the shop is not linked to your account, and `STORE_TOKEN_EXPIRED` (503) when its Etsy authorisation has lapsed and needs reconnecting.


## GET · POST · PUT /api/v1/shops/{shop_id}/listings/{listing_id}/translations/{language}

Manage listing translations

- Operation ID: `listing_translation_get`
- Slug: `listing-translation`
- Category: Store Management
- Authentication: API key plus a connected store. Eto uses that store’s Etsy token, so the shop_id must belong to a store connected to your Eto account or the call answers 403 STORE_NOT_CONNECTED.
- HTML: https://eto.tools/dev/docs/#ep-listing-translation
- Markdown: https://eto.tools/dev/docs/store-management/listing-translation.md
- Operation IDs by method: `listing_translation_get` = GET, `listing_translation_post` = POST, `listing_translation_put` = PUT

Get, create, or update a listing translation for a specific language. Etsy docs: "Listing Translation".

Proxied to the Etsy API at `/v3/application/shops/{shop_id}/listings/{listing_id}/translations/{language}`. Fields Etsy returns are passed through untouched.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `shop_id` | path | `integer` | yes | Your Etsy shop ID |
| `listing_id` | path | `integer` | yes | The listing ID |
| `language` | path | `string` | yes | Language code (e.g. "fr", "de", "es") |

### Request — GET

```bash
curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/shops/12345678/listings/1234567890/translations/fr"
```

```python
import requests

url = "https://eto.tools/api/v1/shops/12345678/listings/1234567890/translations/fr"
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/shops/12345678/listings/1234567890/translations/fr";

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

### Request — POST

```bash
curl -X POST "https://eto.tools/api/v1/shops/12345678/listings/1234567890/translations/fr" \
  -H "X-Eto-API-Key: eto_your_key"
```

```python
import requests

url = "https://eto.tools/api/v1/shops/12345678/listings/1234567890/translations/fr"
headers = {"X-Eto-API-Key": "eto_your_key"}

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

```javascript
const url = "https://eto.tools/api/v1/shops/12345678/listings/1234567890/translations/fr";

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

### Request — PUT

```bash
curl -X PUT "https://eto.tools/api/v1/shops/12345678/listings/1234567890/translations/fr" \
  -H "X-Eto-API-Key: eto_your_key"
```

```python
import requests

url = "https://eto.tools/api/v1/shops/12345678/listings/1234567890/translations/fr"
headers = {"X-Eto-API-Key": "eto_your_key"}

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

```javascript
const url = "https://eto.tools/api/v1/shops/12345678/listings/1234567890/translations/fr";

const response = await fetch(url, {
  method: "PUT",
  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`, passed through from Etsy’s `/v3/application/shops/{shop_id}/listings/{listing_id}/translations/{language}` verbatim. The field-by-field data model is in the [v2 preview reference](https://eto.tools/eto-dev-api-v2/), which documents these same routes alongside the whole Etsy schema.

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

This endpoint can additionally return `STORE_NOT_CONNECTED` (403) when the shop is not linked to your account, and `STORE_TOKEN_EXPIRED` (503) when its Etsy authorisation has lapsed and needs reconnecting.