> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bullionwale.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Deliveries

> Your physical-delivery requests and their status.

A delivery request asks Bullionwale to deliver the metal of one of your orders physically. You make requests on the web or in the Bullionwale app; through the API you can **read** them and follow each one from `pending` to `approved` or `rejected`. The API does not create, change or cancel delivery requests.

| Call | Endpoint | Scope |
| - | - | - |
| [List deliveries](#read-your-deliveries) | `GET /deliveries` | `orders:read` |
| [One delivery](#read-one-delivery) | `GET /deliveries/{delivery_id}` | `orders:read` |

| Environment | List | One delivery |
| - | - | - |
| Test | `/api/trading/test/v1/deliveries` | `/api/trading/test/v1/deliveries/{delivery_id}` |
| Production | `/api/trading/v1/deliveries` | `/api/trading/v1/deliveries/{delivery_id}` |

## The delivery object

| Field | Type | Meaning |
| - | - | - |
| `id` | string | The request's id (a UUID). Use it with `GET /deliveries/{delivery_id}`. |
| `status` | string | `pending`, `approved` or `rejected` (below). |
| `note` | string or null | Bullionwale's note, for example collection details or why a request was rejected. |
| `order_id` | string | The order whose metal is to be delivered. Read it with `GET /orders/{order_id}` (see [Orders](/api-reference/orders/overview)). |
| `deal_no` | integer or null | The order's deal number. |
| `symbol_code` | string | The order's symbol. |
| `quantity` | string | The order's quantity, in `unit`, as a decimal string. |
| `unit` | string | `g` or `kg`: the measure of the symbol's quantity, as on the order. |
| `order_total` | string or null | The order's value in rupees, 2 decimals. |
| `requested_at` | string or null | When you made the request (ISO 8601 with its offset). |
| `decided_at` | string or null | When Bullionwale approved or rejected it; `null` while it is `pending`. |

| `status` | Meaning |
| - | - |
| `pending` | Waiting for Bullionwale's decision. `decided_at` is `null`. |
| `approved` | Bullionwale accepted the request. `note` may say how and where to collect. |
| `rejected` | Bullionwale declined the request. `note` usually says why. |

`quantity` and `unit` follow the order: a gold symbol quoted per 10 grams is in grams, never in 10 g lots (see [Units and pricing](/units-and-pricing)).

## Read your deliveries

```bash curl theme={null}
curl -s https://api.bullionwale.com/api/trading/test/v1/deliveries \
  -H "X-API-Key: $BULLIONWALE_API_KEY"
```

```python Python theme={null}
import os
import requests

BASE = "https://api.bullionwale.com/api/trading/test/v1"
HEADERS = {"X-API-Key": os.environ["BULLIONWALE_API_KEY"]}

for d in requests.get(f"{BASE}/deliveries", headers=HEADERS, timeout=10).json()["items"]:
    print(d["id"], d["status"], d["quantity"], d["unit"])
```

On test the list is always empty:

```json 200 OK theme={null}
{
  "items": [],
  "total": 0
}
```

On production, with one decided request:

```json 200 OK theme={null}
{
  "items": [
    {"id": "5b8e2f10-3c4d-4e6f-9a1b-2c3d4e5f6a7b", "status": "approved",
     "note": "Collect from the counter", "order_id": "3f0c6a52-8a3e-4b8e-9a52-6d2f1c7e9b10",
     "deal_no": 240117, "symbol_code": "GOLD_TRADE_999", "quantity": "10", "unit": "g",
     "order_total": "141250.00", "requested_at": "2026-10-20T07:01:00+00:00",
     "decided_at": "2026-10-20T09:00:00+00:00"}
  ],
  "total": 1
}
```

The list is newest first. It takes `limit` (1 to 200, default 50) and `offset`, like `GET /orders`; `total` counts all your requests.

## Read one delivery

`GET /deliveries/{delivery_id}` returns one request in the same shape, for example to follow a `pending` request:

```json 200 OK theme={null}
{
  "id": "5b8e2f10-3c4d-4e6f-9a1b-2c3d4e5f6a7b",
  "status": "pending",
  "note": null,
  "order_id": "3f0c6a52-8a3e-4b8e-9a52-6d2f1c7e9b10",
  "deal_no": 240117,
  "symbol_code": "GOLD_TRADE_999",
  "quantity": "10",
  "unit": "g",
  "order_total": "141250.00",
  "requested_at": "2026-10-20T07:01:00+00:00",
  "decided_at": null
}
```

A delivery id that is unknown, malformed or another account's answers the same:

```json 404 Not Found theme={null}
{
  "detail": {
    "code": "delivery_not_found",
    "message": "Delivery request not found."
  }
}
```

A decision is not urgent to learn about: poll a `pending` request occasionally (every few minutes is plenty), not in a tight loop.

## Test and production

* **Test has no delivery flow.** The test list is always empty, and one delivery is always `404 delivery_not_found`. Write your code against the shapes above and the production behaviour.
* **Production** lists your real requests, made on the web or in the app.
* If Bullionwale does not offer physical delivery on this platform, the production list is empty and one delivery is `404 delivery_not_found`, as on the web.

## Errors

| Code | Status | Meaning |
| - | - | - |
| `delivery_not_found` | 404 | `GET /deliveries/{delivery_id}`: no such request on your account. Always on test. |
| `insufficient_scope` | 403 | The key does not have `orders:read`. |
| `rate_limited` | 429 | The key's read budget is used up. Wait `Retry-After` seconds. |

Every code is in the [Error reference](/api-reference/error-reference).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.