# Order Lookup

Retrieve order details and status programmatically. Use this to check individual order status, build order history views, or reconcile transactions.

## List orders

Retrieve a list of orders for your partner account, with optional filtering.


```
GET /{partnerRef}/v2/orders
```

### Query parameters

| Parameter | Required | Type | Description |
|  --- | --- | --- | --- |
| `start` | Yes | string | Start date filter (ISO 8601 date, e.g., `2024-03-01`). |
| `end` | Yes | string | End date filter (ISO 8601 date, e.g., `2024-03-31`). |
| `status` | No | string | Filter by order status (e.g., `complete`, `expired`, `pending`). See [Order Statuses](/products/hosted-checkout/docs/transaction-lifecycle/order-statuses). |
| `externalCustomerId` | No | string | Filter orders for a specific customer by your internal ID. |
| `page` | No | string | Page number for pagination. |
| `limit` | No | string | Number of results per page. |
| `skip` | No | string | Number of records to skip. |


### Example


```bash
curl -X GET "https://api.banxa-sandbox.com/{partnerRef}/v2/orders" \
  -H "x-api-key: YOUR_API_KEY" \
  -G \
  --data-urlencode "start=2024-03-01" \
  --data-urlencode "end=2024-03-31" \
  --data-urlencode "status=complete"
```

### Response


```json
{
  "orders": [
    {
      "id": "191fa5b4b1f45e1cf784422e09317d56",
      "externalId": "a4b427ccb872a1744b317456bd0d165f",
      "externalCustomerId": "testing123",
      "country": "US",
      "orderType": "BUY",
      "orderStatusUrl": "https://banxa.status/a4b427ccb872a1744b317456bd0d165f",
      "status": "complete",
      "createdAt": "2022-08-22T09:10:43.724Z",
      "updatedAt": "2022-08-22T09:13:56.165Z",
      "crypto": {
        "id": "USDC",
        "blockchain": "TRON",
        "address": "0x0000000000000000000000000000000000000000",
        "network": "1"
      },
      "fiat": "CAD",
      "fiatAmount": "1000.00",
      "cryptoAmount": "696.63",
      "paymentMethodId": "aabkd8792kd",
      "paymentMethodName": "debit-credit-card",
      "processingFee": "0.30",
      "networkFee": "1.67",
      "partnerFee": "",
      "walletAddress": "0x75b8d4d81377d4b0f11798779563462264914a24",
      "walletAddressTag": "1651352",
      "transactionHash": "0x5ea06c4724e8119704a1b57c918acf31742eb06cdf3f8678fdb17f41bbaf968e",
      "metadata": "{'tracking_id': 'HSKJDGHKSJG0393LJKJF'}"
    }
  ],
  "pageTotal": 10,
  "total": 2654
}
```

| Field | Description |
|  --- | --- |
| `orders` | Array of order objects. |
| `pageTotal` | Number of orders on this page. |
| `total` | Total number of orders matching the query. |
| `fiat` | Fiat currency code (string). |
| `crypto` | Nested object with `id`, `blockchain`, `address`, `network`. |


## Get a specific order

Retrieve full details for a single order by ID.


```
GET /{partnerRef}/v2/orders/{orderId}
```

### Path parameters

| Parameter | Description |
|  --- | --- |
| `orderId` | The Banxa order ID. |


### Example


```bash
curl -X GET "https://api.banxa-sandbox.com/{partnerRef}/v2/orders/191fa5b4b1f45e1cf784422e09317d56" \
  -H "x-api-key: YOUR_API_KEY"
```

### Response


```json
{
  "id": "191fa5b4b1f45e1cf784422e09317d56",
  "externalId": "a4b427ccb872a1744b317456bd0d165f",
  "externalCustomerId": "testing123",
  "country": "US",
  "orderType": "BUY",
  "orderStatusUrl": "https://banxa.status/a4b427ccb872a1744b317456bd0d165f",
  "status": "complete",
  "createdAt": "2022-08-22T09:10:43.724Z",
  "updatedAt": "2022-08-22T09:13:56.165Z",
  "crypto": {
    "id": "USDC",
    "blockchain": "TRON",
    "address": "0x0000000000000000000000000000000000000000",
    "network": "1"
  },
  "fiat": "CAD",
  "fiatAmount": "1000.00",
  "cryptoAmount": "696.63",
  "paymentMethodId": "apple-pay",
  "paymentMethodName": "Apple Pay",
  "processingFee": "0.30",
  "networkFee": "1.67",
  "walletAddress": "0x75b8d4d81377d4b0f11798779563462264914a24",
  "walletAddressTag": "1651352",
  "transactionHash": "0x5ea06c4724e8119704a1b57c918acf31742eb06cdf3f8678fdb17f41bbaf968e",
  "metadata": "{'tracking_id': 'HSKJDGHKSJG0393LJKJF'}"
}
```

## Error responses

| Status | Description |
|  --- | --- |
| `400 Bad Request` | Invalid parameter format. Response includes an error message describing the issue. |
| `404 Not Found` | Order not found. |