---
updatedAt: 2025-05-13T09:54:51.000Z
agentTools:
  projectIndex: https://developers.virtualincentives.com/llms.txt
---

# Listing Orders by Order Status

**Endpoint:** *`https://rest.virtualincentives.com/{version}/{format}/order/status`*

**Method:** `POST`

# Definitions

| Field     | Type                          | Description                                                                                      |
| --------- | ----------------------------- | ------------------------------------------------------------------------------------------------ |
| programid | **required**<br/>integer      | The `programid` that the order was placed against.                                               |
| status    | string(50)                    | Order status of the requested order.                                                             |
| number    | **response only** integer     | Order number for the requested order.                                                            |
| clientid  | **response only**<br/>integer | Client supplied unique identifier for the order. See [Appendix A](https://developers.virtualincentives.com/docs/appendix) for definitions. |

# Examples

## Request XML

```text
<orders>
 <programid>26490</programid>
 <status>completed</status>
</orders>
```

## Response XML

```text
<orders>
 <programid>26490</programid>
 <status>completed</status>
 <order>
  <number>24681234</number>
  <clientid>56258125</clientid>
  <status>completed</status>
 </order>
</orders>
```

## Request JSON

```text
{
 "orders":{
  "programid":"26490",
  "status":"pending"
 }
}
```

## Response JSON

```text
{
 "orders":{
  "programid":"26490",
  "status":"pending",
  "order":[
   {
    "number":"24686669",
    "clientid":"56258125",
    "status":"pending"
   },
   {
    "number":"24686670",
    "clientid":"56258126",
    "status":"pending"
   },
   {
    "number":"24686671",
    "clientid":"56258127",
    "status":"pending"
   },
   {
    "number":"24686672",
    "clientid":"56258128",
    "status":"pending"
   }
  ]
 }
}
```