# Ship some items of an order under one tracking number

> Eto API reference for `POST /api/v1/orders/{shop_id}/{receipt_id}/packages`. 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).

## POST /api/v1/orders/{shop_id}/{receipt_id}/packages

Ship some items of an order under one tracking number

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

Split fulfilment: send ONE package (box) of an order to Etsy with its own tracking number. Body: `transaction_ids` (Etsy transaction ids of the items in the box; all units of an item go together), `tracking_code`, `carrier_name` (Etsy carrier slug, e.g. "usps", "royal-mail"), optional `note_to_buyer` and `client_key` (any 8-64 letters, digits, - or _; send the same key when you retry so the box is never sent twice). Each package EMAILS THE BUYER (Etsy). Etsy marks the whole receipt shipped after the first package; Eto keeps the other items open until their own package is sent, so read `supplier_progress`, not `is_shipped`, to know what is left. Answers 200 `state: "sent"`; 202 `state: "sending"` when Etsy did not answer in time (do NOT resend; Eto confirms it on the next sync); 502 UPSTREAM_ERROR when Etsy refused it (nothing was emailed; fix and retry); 409 PACKAGE_CONFLICT when an item already shipped or the tracking number is already on the order; 403 SUPPLIER_ROUTING_OFF when the account has no supplier yet (assign one, or use shop_order_tracking instead). One Etsy call.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `shop_id` | path | `integer` | yes | Connected shop id |
| `receipt_id` | path | `integer` | yes | Etsy receipt id |
| `transaction_ids` | body | `array` | yes | Etsy transaction ids in this box |
| `tracking_code` | body | `string` | yes | Tracking number |
| `carrier_name` | body | `string` | yes | Etsy carrier slug |
| `note_to_buyer` | body | `string` | no | Message Etsy sends with the tracking |
| `client_key` | body | `string` | no | Idempotency key; reuse it on retries |

### Request

```bash
curl -X POST -H "X-Eto-API-Key: eto_your_key" -H "Content-Type: application/json" -d '{"transaction_ids": [4123456789], "tracking_code": "9400111899223344556677", "carrier_name": "usps", "client_key": "box-3456789012-1"}' "https://eto.tools/api/v1/orders/12345678/3456789012/packages"
```

```python
import requests

url = "https://eto.tools/api/v1/orders/12345678/3456789012/packages"
headers = {"X-Eto-API-Key": "eto_your_key"}
payload = {
    "transaction_ids": [
        4123456789
    ],
    "tracking_code": "9400111899223344556677",
    "carrier_name": "usps",
    "client_key": "box-3456789012-1"
}

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/orders/12345678/3456789012/packages";
const payload = {
  "transaction_ids": [
    4123456789
  ],
  "tracking_code": "9400111899223344556677",
  "carrier_name": "usps",
  "client_key": "box-3456789012-1"
};

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

```json
{
  "state": "sent",
  "package": {"id": 812, "tracking_code": "9400111899223344556677", "carrier_name": "usps",
              "status": "sent", "receipt_shipping_id": 1234567890},
  "message": "",
  "items": {"4123456789": {"id": 41, "name": "Anna (mugs)", "source": "product", "done": true,
            "done_reason": "package", "package_id": 812}},
  "supplier_progress": [{"supplier_id": 41, "name": "Anna (mugs)", "done": 1, "total": 1},
                        {"supplier_id": 42, "name": "Ben", "done": 0, "total": 1}]
}
```

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