# Shop Policies — Eto API

> Return policies, shop sections and listing requirements.

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/shops/{shop_id}/return-policies](https://eto.tools/dev/docs/shop-policies/shop-return-policies.md): Get return policies
- [GET /api/v1/shops/{shop_id}/production-partners](https://eto.tools/dev/docs/shop-policies/shop-production-partners.md): Get production partners
- [GET/POST /api/v1/shops/{shop_id}/listing-requirements](https://eto.tools/dev/docs/shop-policies/shop-listing-requirements.md): Listing requirements
- [POST /api/v1/shops/{shop_id}/return-policies](https://eto.tools/dev/docs/shop-policies/return-policy-create.md): Create return policy
- [GET/PUT/DELETE /api/v1/shops/{shop_id}/return-policies/{policy_id}](https://eto.tools/dev/docs/shop-policies/return-policy-detail.md): Get, update, or delete a return policy
- [POST /api/v1/shops/{shop_id}/return-policies/consolidate](https://eto.tools/dev/docs/shop-policies/return-policy-consolidate.md): Consolidate return policies
- [GET /api/v1/shops/{shop_id}/return-policies/{policy_id}/listings](https://eto.tools/dev/docs/shop-policies/return-policy-listings.md): Get listings with a return policy
- [GET /api/v1/shops/{shop_id}/holiday-preferences](https://eto.tools/dev/docs/shop-policies/shop-holidays.md): Get holiday preferences
- [PUT /api/v1/shops/{shop_id}/holiday-preferences/{holiday_id}](https://eto.tools/dev/docs/shop-policies/shop-holiday-update.md): Update a holiday preference
- [GET/PUT/DELETE /api/v1/shops/{shop_id}/listing-requirements/{requirement_id}](https://eto.tools/dev/docs/shop-policies/listing-requirement-detail.md): Get, update, or delete a listing requirement
- [GET /api/v1/stores/{shop_id}/shipping-profiles/live](https://eto.tools/dev/docs/shop-policies/shipping-profiles-live.md): Get current shipping profiles (live, no cache)
- [GET /api/v1/stores/{shop_id}/return-policies/live](https://eto.tools/dev/docs/shop-policies/return-policies-live.md): Get current return policies (live, no cache)
- [GET /api/v1/stores/{shop_id}/processing-profiles/live](https://eto.tools/dev/docs/shop-policies/processing-profiles-live.md): Get current processing profiles (live, no cache)
- [GET /api/v1/stores/{shop_id}/shop-sections/live](https://eto.tools/dev/docs/shop-policies/shop-sections-live.md): Get current shop sections (live, no cache)

## GET /api/v1/shops/{shop_id}/return-policies

Get return policies

- Operation ID: `shop_return_policies`
- Slug: `shop-return-policies`
- Category: Shop Policies
- 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-return-policies
- Markdown: https://eto.tools/dev/docs/shop-policies/shop-return-policies.md

Retrieve return policy details for your shop.

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

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `shop_id` | path | `integer` | yes | Your Etsy shop ID |

### Request

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

```python
import requests

url = "https://eto.tools/api/v1/shops/12345678/return-policies"
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/return-policies";

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}/policies/return` 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}/production-partners

Get production partners

- Operation ID: `shop_production_partners`
- Slug: `shop-production-partners`
- Category: Shop Policies
- 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-production-partners
- Markdown: https://eto.tools/dev/docs/shop-policies/shop-production-partners.md

List production partners (e.g. print-on-demand services) for your shop.

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

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `shop_id` | path | `integer` | yes | Your Etsy shop ID |

### Request

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

```python
import requests

url = "https://eto.tools/api/v1/shops/12345678/production-partners"
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/production-partners";

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}/production-partners` 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 /api/v1/shops/{shop_id}/listing-requirements

Listing requirements

- Operation ID: `shop_listing_requirements_get`
- Slug: `shop-listing-requirements`
- Category: Shop Policies
- 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-requirements
- Markdown: https://eto.tools/dev/docs/shop-policies/shop-listing-requirements.md
- Operation IDs by method: `shop_listing_requirements_get` = GET, `shop_listing_requirements_post` = POST

Get or create listing readiness requirements — the checklist items a listing must complete before going live. Etsy docs: "Readiness State Definitions".

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

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `shop_id` | path | `integer` | yes | Your Etsy shop ID |

### Request — GET

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

```python
import requests

url = "https://eto.tools/api/v1/shops/12345678/listing-requirements"
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/listing-requirements";

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/listing-requirements" \
  -H "X-Eto-API-Key: eto_your_key"
```

```python
import requests

url = "https://eto.tools/api/v1/shops/12345678/listing-requirements"
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/listing-requirements";

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}/readiness-state-definitions` 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.


## POST /api/v1/shops/{shop_id}/return-policies

Create return policy

- Operation ID: `return_policy_create`
- Slug: `return-policy-create`
- Category: Shop Policies
- 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-return-policy-create
- Markdown: https://eto.tools/dev/docs/shop-policies/return-policy-create.md

Create a new return policy for your shop. Etsy docs: "Create Return Policy".

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

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `shop_id` | path | `integer` | yes | Your Etsy shop ID |

### Request

```bash
curl -X POST -H "X-Eto-API-Key: eto_your_key" -H "Content-Type: application/json" -d '{"accepts_returns": true, "return_deadline": 30}' "https://eto.tools/api/v1/shops/12345678/return-policies"
```

```python
import requests

url = "https://eto.tools/api/v1/shops/12345678/return-policies"
headers = {"X-Eto-API-Key": "eto_your_key"}
payload = {
    "accepts_returns": True,
    "return_deadline": 30
}

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

```javascript
const url = "https://eto.tools/api/v1/shops/12345678/return-policies";
const payload = {
  "accepts_returns": true,
  "return_deadline": 30
};

const response = await fetch(url, {
  method: "POST",
  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}/policies/return` 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 · PUT · DELETE /api/v1/shops/{shop_id}/return-policies/{policy_id}

Get, update, or delete a return policy

- Operation ID: `return_policy_detail_get`
- Slug: `return-policy-detail`
- Category: Shop Policies
- 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-return-policy-detail
- Markdown: https://eto.tools/dev/docs/shop-policies/return-policy-detail.md
- Operation IDs by method: `return_policy_detail_get` = GET, `return_policy_detail_put` = PUT, `return_policy_detail_delete` = DELETE

Manage a specific return policy. Etsy docs: "Shop Return Policy".

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

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `shop_id` | path | `integer` | yes | Your Etsy shop ID |
| `policy_id` | path | `integer` | yes | The return policy ID |

### Request — GET

```bash
curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/shops/12345678/return-policies/54321"
```

```python
import requests

url = "https://eto.tools/api/v1/shops/12345678/return-policies/54321"
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/return-policies/54321";

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 — PUT

```bash
curl -X PUT "https://eto.tools/api/v1/shops/12345678/return-policies/1" \
  -H "X-Eto-API-Key: eto_your_key"
```

```python
import requests

url = "https://eto.tools/api/v1/shops/12345678/return-policies/1"
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/return-policies/1";

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

### Request — DELETE

```bash
curl -X DELETE "https://eto.tools/api/v1/shops/12345678/return-policies/1" \
  -H "X-Eto-API-Key: eto_your_key"
```

```python
import requests

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

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

```javascript
const url = "https://eto.tools/api/v1/shops/12345678/return-policies/1";

const response = await fetch(url, {
  method: "DELETE",
  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}/policies/return/{policy_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.


## POST /api/v1/shops/{shop_id}/return-policies/consolidate

Consolidate return policies

- Operation ID: `return_policy_consolidate`
- Slug: `return-policy-consolidate`
- Category: Shop Policies
- 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-return-policy-consolidate
- Markdown: https://eto.tools/dev/docs/shop-policies/return-policy-consolidate.md

Merge multiple return policies into one. Etsy docs: "Consolidate Return Policies".

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

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `shop_id` | path | `integer` | yes | Your Etsy shop ID |

### Request

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

```python
import requests

url = "https://eto.tools/api/v1/shops/12345678/return-policies/consolidate"
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/return-policies/consolidate";

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}/policies/return/consolidate` 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}/return-policies/{policy_id}/listings

Get listings with a return policy

- Operation ID: `return_policy_listings`
- Slug: `return-policy-listings`
- Category: Shop Policies
- 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-return-policy-listings
- Markdown: https://eto.tools/dev/docs/shop-policies/return-policy-listings.md

Get all listings that use a specific return policy. Etsy docs: "Listings By Return Policy".

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

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `shop_id` | path | `integer` | yes | Your Etsy shop ID |
| `policy_id` | path | `integer` | yes | The return policy ID |

### Request

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

```python
import requests

url = "https://eto.tools/api/v1/shops/12345678/return-policies/54321/listings"
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/return-policies/54321/listings";

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}/policies/return/{policy_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.


## GET /api/v1/shops/{shop_id}/holiday-preferences

Get holiday preferences

- Operation ID: `shop_holidays`
- Slug: `shop-holidays`
- Category: Shop Policies
- 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-holidays
- Markdown: https://eto.tools/dev/docs/shop-policies/shop-holidays.md

Get your shop's holiday settings (when you're on vacation). Etsy docs: "Holiday Preferences".

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

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `shop_id` | path | `integer` | yes | Your Etsy shop ID |

### Request

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

```python
import requests

url = "https://eto.tools/api/v1/shops/12345678/holiday-preferences"
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/holiday-preferences";

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}/holiday-preferences` 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.


## PUT /api/v1/shops/{shop_id}/holiday-preferences/{holiday_id}

Update a holiday preference

- Operation ID: `shop_holiday_update`
- Slug: `shop-holiday-update`
- Category: Shop Policies
- 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-holiday-update
- Markdown: https://eto.tools/dev/docs/shop-policies/shop-holiday-update.md

Update vacation/holiday settings. Etsy docs: "Update Holiday Preferences".

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

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `shop_id` | path | `integer` | yes | Your Etsy shop ID |
| `holiday_id` | path | `integer` | yes | The holiday ID |

### Request

```bash
curl -X PUT -H "X-Eto-API-Key: eto_your_key" -H "Content-Type: application/json" -d '{"is_working": false}' "https://eto.tools/api/v1/shops/12345678/holiday-preferences/1"
```

```python
import requests

url = "https://eto.tools/api/v1/shops/12345678/holiday-preferences/1"
headers = {"X-Eto-API-Key": "eto_your_key"}
payload = {
    "is_working": False
}

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

```javascript
const url = "https://eto.tools/api/v1/shops/12345678/holiday-preferences/1";
const payload = {
  "is_working": false
};

const response = await fetch(url, {
  method: "PUT",
  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}/holiday-preferences/{holiday_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 · PUT · DELETE /api/v1/shops/{shop_id}/listing-requirements/{requirement_id}

Get, update, or delete a listing requirement

- Operation ID: `listing_requirement_detail_get`
- Slug: `listing-requirement-detail`
- Category: Shop Policies
- 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-requirement-detail
- Markdown: https://eto.tools/dev/docs/shop-policies/listing-requirement-detail.md
- Operation IDs by method: `listing_requirement_detail_get` = GET, `listing_requirement_detail_put` = PUT, `listing_requirement_detail_delete` = DELETE

Manage a specific listing readiness requirement. Etsy docs: "Readiness State Definition".

Proxied to the Etsy API at `/v3/application/shops/{shop_id}/readiness-state-definitions/{requirement_id}`. Fields Etsy returns are passed through untouched.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `shop_id` | path | `integer` | yes | Your Etsy shop ID |
| `requirement_id` | path | `integer` | yes | The requirement ID |

### Request — GET

```bash
curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/shops/12345678/listing-requirements/99999"
```

```python
import requests

url = "https://eto.tools/api/v1/shops/12345678/listing-requirements/99999"
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/listing-requirements/99999";

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 — PUT

```bash
curl -X PUT "https://eto.tools/api/v1/shops/12345678/listing-requirements/1" \
  -H "X-Eto-API-Key: eto_your_key"
```

```python
import requests

url = "https://eto.tools/api/v1/shops/12345678/listing-requirements/1"
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/listing-requirements/1";

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

### Request — DELETE

```bash
curl -X DELETE "https://eto.tools/api/v1/shops/12345678/listing-requirements/1" \
  -H "X-Eto-API-Key: eto_your_key"
```

```python
import requests

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

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

```javascript
const url = "https://eto.tools/api/v1/shops/12345678/listing-requirements/1";

const response = await fetch(url, {
  method: "DELETE",
  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}/readiness-state-definitions/{requirement_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/stores/{shop_id}/shipping-profiles/live

Get current shipping profiles (live, no cache)

- Operation ID: `shipping_profiles_live`
- Slug: `shipping-profiles-live`
- Category: Shop Policies
- Authentication: API key only. Reads or writes data Eto holds for your own account.
- HTML: https://eto.tools/dev/docs/#ep-shipping-profiles-live
- Markdown: https://eto.tools/dev/docs/shop-policies/shipping-profiles-live.md

Returns this shop's shipping profiles RIGHT NOW — fetched live from Etsy on every call, never from the local cache. Use this when you need the absolute latest IDs to put into shops[].shipping_profile_id when calling POST /api/v1/listings/create.

One Etsy API call per request. Response is a flat list — pick the shipping_profile_id you want.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `shop_id` | path | `integer` | yes | Your connected Etsy shop ID. Get the list from GET /api/v1/stores. |

### Request

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

```python
import requests

url = "https://eto.tools/api/v1/stores/12345678/shipping-profiles/live"
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/shipping-profiles/live";

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
{
  "shop_id": "12345678",
  "fetched_at": "2026-04-19T14:30:00Z",
  "count": 2,
  "shipping_profiles": [
    {
      "shipping_profile_id": 291257702631,
      "title": "Standard Shipping",
      "min_processing_days": 1,
      "max_processing_days": 3,
      "processing_days_display_label": "1-3 business days",
      "origin_country_iso": "US",
      "origin_postal_code": "10001",
      "profile_type": "manual",
      "domestic_handling_fee": 0.00,
      "international_handling_fee": 0.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}/return-policies/live

Get current return policies (live, no cache)

- Operation ID: `return_policies_live`
- Slug: `return-policies-live`
- Category: Shop Policies
- Authentication: API key only. Reads or writes data Eto holds for your own account.
- HTML: https://eto.tools/dev/docs/#ep-return-policies-live
- Markdown: https://eto.tools/dev/docs/shop-policies/return-policies-live.md

Returns this shop's return policies RIGHT NOW — fetched live from Etsy on every call. No cache, no staleness. Use this to get the return_policy_id to plug into shops[].return_policy_id when calling POST /api/v1/listings/create.

One Etsy API call per request.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `shop_id` | path | `integer` | yes | Your connected Etsy shop ID. |

### Request

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

```python
import requests

url = "https://eto.tools/api/v1/stores/12345678/return-policies/live"
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/return-policies/live";

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
{
  "shop_id": "12345678",
  "fetched_at": "2026-04-19T14:30:00Z",
  "count": 1,
  "return_policies": [
    {
      "return_policy_id": 1435074483195,
      "accepts_returns": true,
      "accepts_exchanges": true,
      "return_deadline": 30
    }
  ]
}
```

### 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}/processing-profiles/live

Get current processing profiles (live, no cache)

- Operation ID: `processing_profiles_live`
- Slug: `processing-profiles-live`
- Category: Shop Policies
- Authentication: API key only. Reads or writes data Eto holds for your own account.
- HTML: https://eto.tools/dev/docs/#ep-processing-profiles-live
- Markdown: https://eto.tools/dev/docs/shop-policies/processing-profiles-live.md

Returns this shop's processing profiles (Etsy "readiness state definitions") RIGHT NOW — fetched live from Etsy on every call. No cache. Use this to get the processing_profile_id (a.k.a. readiness_state_id) for shops[].processing_profile_id when calling POST /api/v1/listings/create.

One Etsy API call per request.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `shop_id` | path | `integer` | yes | Your connected Etsy shop ID. |

### Request

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

```python
import requests

url = "https://eto.tools/api/v1/stores/12345678/processing-profiles/live"
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/processing-profiles/live";

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
{
  "shop_id": "12345678",
  "fetched_at": "2026-04-19T14:30:00Z",
  "count": 1,
  "processing_profiles": [
    {
      "readiness_state_id": 1456101932490,
      "readiness_state": "ready_to_ship",
      "min_processing_days": 1,
      "max_processing_days": 3,
      "processing_days_display_label": "1-3 business days"
    }
  ]
}
```

### 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}/shop-sections/live

Get current shop sections (live, no cache)

- Operation ID: `shop_sections_live`
- Slug: `shop-sections-live`
- Category: Shop Policies
- Authentication: API key only. Reads or writes data Eto holds for your own account.
- HTML: https://eto.tools/dev/docs/#ep-shop-sections-live
- Markdown: https://eto.tools/dev/docs/shop-policies/shop-sections-live.md

Returns this shop's sections RIGHT NOW — fetched live from Etsy on every call. No cache. Use this to get the shop_section_id to plug into shops[].shop_section_id when calling POST /api/v1/listings/create.

One Etsy API call per request.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `shop_id` | path | `integer` | yes | Your connected Etsy shop ID. |

### Request

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

```python
import requests

url = "https://eto.tools/api/v1/stores/12345678/shop-sections/live"
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/shop-sections/live";

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
{
  "shop_id": "12345678",
  "fetched_at": "2026-04-19T14:30:00Z",
  "count": 2,
  "shop_sections": [
    {
      "shop_section_id": 56909368,
      "title": "New Arrivals",
      "rank": 1,
      "user_id": 99887766,
      "active_listing_count": 15
    }
  ]
}
```

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