# Create a drop-ship order (recipient + lines)

`POST /api/v1/dropship-orders` — Token required · df:write · write · 2 pts

Drop-ship orders

## Request body (JSON)

| Field | Type | Description |
| --- | --- | --- |
| `warehouse_code` **required** | string | Warehouse code: AU (Australia, all warehouses — aggregate view), AUSYD2 (Sydney main, Rosehill), AUSYD1 (Sydney accessories), CN (China, all warehouses — aggregate view), CHNZJ1 (Zhenjiang). Full list: GET /api/v1/warehouses. |
| `sku` **required** | string | SKU / barcode — the **colour + size** level, e.g. OB0021611. For the whole style use product_code instead. (max length 64) |
| `quantity` **required** | integer | Quantity, a positive integer, e.g. 2. In reservation adjustments / carts, 0 removes the line. (1–99999) |
| `recipient` **required** | object | Recipient object { name, phone, address, country_code, state, city, postal_code }. country_code is AU / CN / NZ; state, city and postal_code are required for AU and NZ. Include the country code in the phone for cross-border parcels (e.g. +61…) and the street number in the address — incomplete addresses are the top cause of failed delivery. |
| `recipient.name` **required** | string | Recipient name. (max length 128) |
| `recipient.phone` **required** | string | Recipient phone; include the country code for cross-border parcels, e.g. +61… (max length 64) |
| `recipient.address` **required** | string | Delivery address including the street number — incomplete addresses are the top cause of failed delivery. (max length 512) |
| `recipient.country_code` **required** | string | Destination country: AU / CN / NZ (drop-ship supports these three). |
| `recipient.state` | string | State / province, e.g. NSW. Required for AU and NZ addresses. (max length 64) |
| `recipient.city` | string | City, e.g. Sydney. Required for AU and NZ addresses. (max length 128) |
| `recipient.postal_code` | string | Postcode, e.g. 2000. Required for AU and NZ addresses. (max length 16) |
| `sender` | object | Sender object { name, phone } (optional), printed on the waybill. |
| `sender.name` | string | Recipient name. (max length 128) |
| `sender.phone` | string | Recipient phone; include the country code for cross-border parcels, e.g. +61… (max length 64) |
| `shipping_method` | string | Shipping method: normal (default), express or ems. |
| `auto_confirm` | boolean | Submit immediately (optional). **Omitted = draft only**, someone confirms it in the ERP before it takes effect — this default is intentional. A submitted drop-ship order is allocated at once and can no longer be edited. |
| `client_order_number` | string | The order number in your own system (the one you sent when creating the drop-ship order). (max length 64) |
| `note` | string | Remark (optional, up to 500 characters). (max length 500) |

## Response

The envelope is decided by the HTTP status alone: 2xx with `{ data: … }` (lists also carry `page / page_size / has_more` or `total_count`); 4xx / 5xx with `{ error: { code, message, hint, request_id, doc_url } }`.

```json
{
  "data": { … }
}
```

A success response carries no human-readable text — no `code / result / msg`. `error.code` is the only field your code should branch on; `message` follows `Accept-Language`.

> Send an `Idempotency-Key` header (any unique string, e.g. a UUID) on writes: a network retry never creates a second order. Orders are drafts by default until a person confirms them in the ERP.

## Examples

### curl

```bash
curl -X POST "https://connect.everugg.net.au/api/v1/dropship-orders" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <uuid>" \
  -d '{ "warehouse_code": "AU", "sku": "OB0021611", "quantity": 2, "recipient": { "name": "Jane Smith", "phone": "+61 400 000 000", "address": "1 Example St, Sydney NSW 2000", "country_code": "AU" } }'
```

### Python

```python
import requests

r = requests.post(
    "https://connect.everugg.net.au/api/v1/dropship-orders",
    headers={"Authorization": "Bearer " + TOKEN, "Idempotency-Key": str(uuid.uuid4())},
    json={
      "warehouse_code": "AU",
      "sku": "OB0021611",
      "quantity": 2,
      "recipient": {
        "name": "Jane Smith",
        "phone": "+61 400 000 000",
        "address": "1 Example St, Sydney NSW 2000",
        "country_code": "AU"
      }
    },
)
data = r.json()
r.raise_for_status()  # 4xx/5xx: data["error"]["code"] / ["hint"]
```

### Node

```js
const res = await fetch("https://connect.everugg.net.au/api/v1/dropship-orders", {
  method: "POST",
  headers: { Authorization: `Bearer ${TOKEN}`, "Content-Type": "application/json", "Idempotency-Key": crypto.randomUUID() },
  body: JSON.stringify({
    "warehouse_code": "AU",
    "sku": "OB0021611",
    "quantity": 2,
    "recipient": {
      "name": "Jane Smith",
      "phone": "+61 400 000 000",
      "address": "1 Example St, Sydney NSW 2000",
      "country_code": "AU"
    }
  }),
})
const data = await res.json()
if (!res.ok) throw new Error(`${data.error?.code}: ${data.error?.message}`)
```

### Java

```java
HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://connect.everugg.net.au/api/v1/dropship-orders"))
    .header("Authorization", "Bearer " + token)
    .header("Content-Type", "application/json")
    .header("Idempotency-Key", UUID.randomUUID().toString())
    .POST(HttpRequest.BodyPublishers.ofString("{ \"warehouse_code\": \"AU\", \"sku\": \"OB0021611\", \"quantity\": 2, \"recipient\": { \"name\": \"Jane Smith\", \"phone\": \"+61 400 000 000\", \"address\": \"1 Example St, Sydney NSW 2000\", \"country_code\": \"AU\" } }"))
    .build();
HttpResponse<String> res = HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString());
```

---
Markdown source: https://connect.everugg.net.au/reference/post-api-v1-dropship-orders.md?lang=en · Web page: https://connect.everugg.net.au/reference?op=post-api-v1-dropship-orders&lang=en