# Read or bulk-set which supplier handles each store and product

> Eto API reference for `GET /api/v1/supplier-assignments`. Base URL `https://eto.tools/api/v1/`. Authenticate with the `X-Eto-API-Key` header.

Part of the [Eto API reference](https://eto.tools/dev/docs/). The full reference in one file is at [llms-full.txt](https://eto.tools/dev/docs/llms-full.txt); the machine-readable schema is at [openapi.json](https://eto.tools/dev/docs/openapi.json).

## GET · PUT /api/v1/supplier-assignments

Read or bulk-set which supplier handles each store and product

- Operation ID: `supplier_assignments_get`
- Slug: `supplier-assignments`
- Category: Orders
- Authentication: API key only. Reads or writes data Eto holds for your own account.
- HTML: https://eto.tools/dev/docs/#ep-supplier-assignments
- Markdown: https://eto.tools/dev/docs/orders/supplier-assignments.md
- Operation IDs by method: `supplier_assignments_get` = GET, `supplier_assignments_put` = PUT

Who handles an order item, first match wins: the item's own choice (PUT .../items/{transaction_id}/supplier), then the product's supplier, then the store default, then nobody. GET returns `store_defaults` and `products` (product assignments, paged by `page`/`limit`, up to 1000), filterable by `shop_id`, `supplier_id` and `listing_ids`. PUT applies up to 1,000 rows in one call: `store_defaults: [{shop_id, supplier_id}]` and `products: [{listing_id, supplier_id}]`; `supplier_id: null` removes the supplier. It is ALL OR NOTHING: every row is checked first (the store is yours, the listing is yours, the supplier is active and can see that store's orders), and one bad row answers 400 VALIDATION_FAILED with every problem in `error.fields` (`kind`, `index`, `error`) and saves nothing. `apply_to_open_orders` (default true) moves open, unshipped items to the new supplier at once; false keeps every open item with its current supplier and only new orders follow. Shipped items never move. To assign thousands of listings, page through your listings (shop_listings_get), decide per listing, and send them in batches of 1,000. Zero Etsy calls.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `shop_id` | query | `string` | no | GET: only this store's default and listings |
| `supplier_id` | query | `integer` | no | GET: only this supplier |
| `listing_ids` | query | `string` | no | GET: comma-separated listing ids |
| `page` | query | `integer` | no | GET: page of products, from 1 |
| `limit` | query | `integer` | no | GET: products per page, 1-1000 (default 500) |
| `store_defaults` | body | `array` | no | PUT: [{"shop_id": "123", "supplier_id": 41 \| null}] |
| `products` | body | `array` | no | PUT: [{"listing_id": 456, "supplier_id": 41 \| null}] |
| `apply_to_open_orders` | body | `boolean` | no | PUT: move open items now (default true) |

### Request — GET

```bash
curl -X GET "https://eto.tools/api/v1/supplier-assignments?shop_id=12345678&supplier_id=1" \
  -H "X-Eto-API-Key: eto_your_key"
```

```python
import requests

url = "https://eto.tools/api/v1/supplier-assignments"
headers = {"X-Eto-API-Key": "eto_your_key"}
params = {
    "shop_id": 12345678,
    "supplier_id": 1
}

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/supplier-assignments?shop_id=12345678&supplier_id=1";

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 -H "X-Eto-API-Key: eto_your_key" -H "Content-Type: application/json" -d '{"products": [{"listing_id": 1789456123, "supplier_id": 41}], "store_defaults": [{"shop_id": "12345678", "supplier_id": 42}]}' "https://eto.tools/api/v1/supplier-assignments"
```

```python
import requests

url = "https://eto.tools/api/v1/supplier-assignments"
headers = {"X-Eto-API-Key": "eto_your_key"}
payload = {
    "products": [
        {
            "listing_id": 1789456123,
            "supplier_id": 41
        }
    ],
    "store_defaults": [
        {
            "shop_id": "12345678",
            "supplier_id": 42
        }
    ]
}

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/supplier-assignments";
const payload = {
  "products": [
    {
      "listing_id": 1789456123,
      "supplier_id": 41
    }
  ],
  "store_defaults": [
    {
      "shop_id": "12345678",
      "supplier_id": 42
    }
  ]
};

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

```json
{
  "success": true,
  "store_defaults_set": 1, "store_defaults_removed": 0,
  "products_set": 1, "products_removed": 0,
  "open_items_moved": 7, "open_items_kept": 0
}
```

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