# Orders — Eto API

> Receipts and fulfilment, both Eto’s synced copy and the live Etsy passthrough.

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}/orders](https://eto.tools/dev/docs/orders/shop-orders.md): List shop orders
- [GET /api/v1/shops/{shop_id}/orders/{order_id}](https://eto.tools/dev/docs/orders/shop-order-detail.md): Get order details
- [POST /api/v1/shops/{shop_id}/orders/{order_id}/tracking](https://eto.tools/dev/docs/orders/shop-order-tracking.md): Update order tracking
- [PUT /api/v1/shops/{shop_id}/orders/{order_id}/update](https://eto.tools/dev/docs/orders/order-update.md): Update an order
- [GET /api/v1/shops/{shop_id}/orders/{order_id}/listings](https://eto.tools/dev/docs/orders/order-listings.md): Get listings in an order
- [GET /api/v1/shops/{shop_id}/orders/{order_id}/payments](https://eto.tools/dev/docs/orders/order-payments.md): Get order payments
- [GET /api/v1/orders/{shop_id}](https://eto.tools/dev/docs/orders/orders-list.md): List orders for a store
- [GET /api/v1/orders/{shop_id}/{receipt_id}](https://eto.tools/dev/docs/orders/order-detail.md): Get one order
- [POST /api/v1/orders/{shop_id}/sync](https://eto.tools/dev/docs/orders/orders-sync.md): Sync orders from Etsy

## GET /api/v1/shops/{shop_id}/orders

List shop orders

- Operation ID: `shop_orders`
- Slug: `shop-orders`
- Category: Orders
- 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-orders
- Markdown: https://eto.tools/dev/docs/orders/shop-orders.md

Get all orders for your shop. Supports filtering by date and pagination. Etsy docs: "Shop Receipts".

Proxied to the Etsy API at `/v3/application/shops/{shop_id}/receipts`. 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 orders (max 100) Default: `25`. |
| `offset` | query | `integer` | no | Pagination offset Default: `0`. |
| `min_created` | query | `integer` | no | Earliest order date (unix seconds) |
| `max_created` | query | `integer` | no | Latest order date (unix seconds) |
| `sort_on` | query | `string` | no | Sort field Default: `created`. |
| `sort_order` | query | `string` | no | Sort direction Default: `desc`. |

### Request

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

```python
import requests

url = "https://eto.tools/api/v1/shops/12345678/orders?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/orders?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}/receipts` 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}/orders/{order_id}

Get order details

- Operation ID: `shop_order_detail`
- Slug: `shop-order-detail`
- Category: Orders
- 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-order-detail
- Markdown: https://eto.tools/dev/docs/orders/shop-order-detail.md

Get full details for a specific order including items, shipping, and payment info. Etsy docs: "Shop Receipt by ID".

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

### Parameters

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

### Request

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

```python
import requests

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

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}/receipts/{order_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}/orders/{order_id}/tracking

Update order tracking

- Operation ID: `shop_order_tracking`
- Slug: `shop-order-tracking`
- Category: Orders
- 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-order-tracking
- Markdown: https://eto.tools/dev/docs/orders/shop-order-tracking.md

Add or update tracking information for an order so the buyer can track their shipment. Etsy docs: "Receipt Tracking".

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

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `shop_id` | path | `integer` | yes | Your Etsy shop ID |
| `order_id` | path | `integer` | yes | The order ID |
| `tracking_code` | body | `string` | yes | Tracking number |
| `carrier_name` | body | `string` | yes | Shipping carrier name |

### Request

```bash
curl -X POST -H "X-Eto-API-Key: eto_your_key" -H "Content-Type: application/json" -d '{"tracking_code": "1Z999AA10123456784", "carrier_name": "ups"}' "https://eto.tools/api/v1/shops/12345678/orders/3344556677/tracking"
```

```python
import requests

url = "https://eto.tools/api/v1/shops/12345678/orders/3344556677/tracking"
headers = {"X-Eto-API-Key": "eto_your_key"}
payload = {
    "tracking_code": "1Z999AA10123456784",
    "carrier_name": "ups"
}

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/orders/3344556677/tracking";
const payload = {
  "tracking_code": "1Z999AA10123456784",
  "carrier_name": "ups"
};

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}/receipts/{order_id}/tracking` 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}/orders/{order_id}/update

Update an order

- Operation ID: `order_update`
- Slug: `order-update`
- Category: Orders
- 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-order-update
- Markdown: https://eto.tools/dev/docs/orders/order-update.md

Update order details like notes or status. Etsy docs: "Update Shop Receipt".

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

### Parameters

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

### Request

```bash
curl -X PUT -H "X-Eto-API-Key: eto_your_key" -H "Content-Type: application/json" -d '{"was_shipped": true}' "https://eto.tools/api/v1/shops/12345678/orders/3344556677/update"
```

```python
import requests

url = "https://eto.tools/api/v1/shops/12345678/orders/3344556677/update"
headers = {"X-Eto-API-Key": "eto_your_key"}
payload = {
    "was_shipped": True
}

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/orders/3344556677/update";
const payload = {
  "was_shipped": true
};

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}/receipts/{order_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}/orders/{order_id}/listings

Get listings in an order

- Operation ID: `order_listings`
- Slug: `order-listings`
- Category: Orders
- 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-order-listings
- Markdown: https://eto.tools/dev/docs/orders/order-listings.md

Get the listings that were purchased in a specific order. Etsy docs: "Listings By Receipt".

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

### Parameters

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

### Request

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

```python
import requests

url = "https://eto.tools/api/v1/shops/12345678/orders/3344556677/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/orders/3344556677/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}/receipts/{order_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}/orders/{order_id}/payments

Get order payments

- Operation ID: `order_payments`
- Slug: `order-payments`
- Category: Orders
- 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-order-payments
- Markdown: https://eto.tools/dev/docs/orders/order-payments.md

Get payment details for a specific order. Etsy docs: "Payment By Receipt ID".

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

### Parameters

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

### Request

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

```python
import requests

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

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}/receipts/{order_id}/payments` 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/orders/{shop_id}

List orders for a store

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

List receipts/orders for a connected store (newest first by default — so for "my latest order" just call this, no date filter). Triggers a background sync so data stays fresh. To filter by date, pass a friendly `period` or `start_date`/`end_date` (resolved server-side in the shop timezone) — do NOT compute unix timestamps. Every order includes `created_iso` (UTC) and `created_local` (shop/your timezone), and the response carries `server_now_utc` + `timezone`, so you never mis-read a raw timestamp or think an order is "in the future".

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `shop_id` | path | `integer` | yes | Connected shop id |
| `limit` | query | `integer` | no | Page size (default 25) |
| `offset` | query | `integer` | no | Pagination offset |
| `period` | query | `string` | no | Friendly date filter: today, yesterday, last_7_days, last_30_days, this_month, last_month. |
| `start_date` | query | `string` | no | Filter from this calendar day "YYYY-MM-DD" (inclusive). |
| `end_date` | query | `string` | no | Filter to this calendar day "YYYY-MM-DD" (inclusive). |
| `timezone` | query | `string` | no | IANA tz for resolving period/dates + formatting created_local (default: shop tz). |
| `min_created` | query | `integer` | no | Advanced: unix lower bound on order creation. Prefer period/start_date. |
| `max_created` | query | `integer` | no | Advanced: unix upper bound on order creation. Prefer period/end_date. |
| `sort_on` | query | `string` | no | Sort field (default "created") |
| `sort_order` | query | `string` | no | asc or desc (default desc) |

### Request

```bash
curl -X GET "https://eto.tools/api/v1/orders/12345678?limit=25&offset=0" \
  -H "X-Eto-API-Key: eto_your_key"
```

```python
import requests

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

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

```javascript
const url = "https://eto.tools/api/v1/orders/12345678?limit=25&offset=0";

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-orders-list) 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.


## GET /api/v1/orders/{shop_id}/{receipt_id}

Get one order

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

Get a single order (receipt) with its transactions for a connected store. Also returns a `profit` object = THIS order's own profit: gross_profit_cents (its gross sale minus its OWN fees, incl remitted tax), fees_cents, fees_breakdown, cogs_cents, net_profit_cents. This is the answer to "profit for this product/order" — it does NOT subtract shop-wide ad spend or other orders' refunds/cancellations. (profit is null until a finance_sync has run.)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `shop_id` | path | `integer` | yes | Connected shop id |
| `receipt_id` | path | `integer` | yes | Etsy receipt id |

### Request

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

```python
import requests

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

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


## POST /api/v1/orders/{shop_id}/sync

Sync orders from Etsy

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

Force a fresh sync of orders for a connected store from Etsy.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `shop_id` | path | `integer` | yes | Connected shop id |

### Request

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

```python
import requests

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

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`. This endpoint has no worked response example in the registry yet; the [HTML reference](https://eto.tools/dev/docs/#ep-orders-sync) 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.