# Allocation preview: per line, how much can be allocated, how much is owed, when pre-sale stock arrives, the amount payable and whether the balance covers it

`POST /api/v1/orders/{order_id}/allocation-preview` — Token required · order:write · write · 2 pts

Wholesale orders

Allocation preview: per line, how much can be allocated, how much is owed, when pre-sale stock arrives, the amount payable and whether the balance covers it. Note: the preview holds stock — submit or cancel afterwards

## Path parameters

| Name | Type | Description |
| --- | --- | --- |
| `order_id` **required** | string | Wholesale order id, from the order list. Own channel only. (max length 64) |

## Request body (JSON)

| Field | Type | Description |
| --- | --- | --- |
| `use_reservation` | boolean | Whether to draw on your reserved (locked) stock for this allocation. Omit = do not use it. |

## 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/orders/{order_id}/allocation-preview" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <uuid>" \
  -d '{ "use_reservation": false }'
```

### Python

```python
import requests

r = requests.post(
    "https://connect.everugg.net.au/api/v1/orders/{order_id}/allocation-preview",
    headers={"Authorization": "Bearer " + TOKEN, "Idempotency-Key": str(uuid.uuid4())},
    json={
      "use_reservation": False
    },
)
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/orders/{order_id}/allocation-preview", {
  method: "POST",
  headers: { Authorization: `Bearer ${TOKEN}`, "Content-Type": "application/json", "Idempotency-Key": crypto.randomUUID() },
  body: JSON.stringify({
    "use_reservation": false
  }),
})
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/orders/{order_id}/allocation-preview"))
    .header("Authorization", "Bearer " + token)
    .header("Content-Type", "application/json")
    .header("Idempotency-Key", UUID.randomUUID().toString())
    .POST(HttpRequest.BodyPublishers.ofString("{ \"use_reservation\": false }"))
    .build();
HttpResponse<String> res = HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString());
```

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