---
updatedAt: 2026-10-14T15:19:02.000Z
---

# Order Management API overview

## Overview

Use the **Order Management API** to view purchase orders (POs) and track PO status changes. A PO can include items shipped to a Walmart or Sam’s Club facility, a distribution center, or directly to a store or club.

Use this API to:

* List Walmart purchase orders
* Filter by status, type, dates, and supplier
* Retrieve details for a single PO, including line items and costs

**Base URLs**

* Production: `https://api-gateway.walmart.com`
* Sandbox: `https://sandbox.walmartapis.com`

**Audience**

* Suppliers to Walmart and Sam’s Club

## Before you begin

* Obtain API credentials and generate an access token.
* Include Walmart headers on every request.
* Use a unique correlation ID per call for traceability.

### Authentication & headers

Use the Authentication Management API to obtain `wm_sec.access_token`. Send the token in the header for each call. Refresh when tokens expire.

<Table align={[null,null,"right",null]}>
  <thead>
    <tr>
      <th>
        Header
      </th>

      <th>
        Type
      </th>

      <th style={{ textAlign: "right" }}>
        Required
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `wm_sec.access_token`
      </td>

      <td>
        string
      </td>

      <td style={{ textAlign: "right" }}>
        Yes
      </td>

      <td>
        Access token from the Token API.
      </td>
    </tr>

    <tr>
      <td>
        `WM_QOS.CORRELATION_ID`
      </td>

      <td>
        string
      </td>

      <td style={{ textAlign: "right" }}>
        Yes
      </td>

      <td>
        Unique ID per request. Use a UUID.
      </td>
    </tr>

    <tr>
      <td>
        `WM_CONSUMER.CHANNEL.TYPE`
      </td>

      <td>
        string
      </td>

      <td style={{ textAlign: "right" }}>
        Yes
      </td>

      <td>
        Identifier that tracks the consumer request by channel.

        Use the consumer channel type received during your onboarding.
      </td>
    </tr>

    <tr>
      <td>
        `Accept`
      </td>

      <td>
        string
      </td>

      <td style={{ textAlign: "right" }}>
        Yes
      </td>

      <td>
        `application/json`
      </td>
    </tr>
  </tbody>
</Table>

## Authentication

Use the Token API to obtain `wm_sec.access_token`. Send the token in the header for each call. Refresh expired tokens.

## Rate limits and pagination

* Default limit per request is up to **100** POs.
* Use the `nextCursor` value from the response to request the next page.
* Current throttle: **5,000 requests per hour**. Plan retries with exponential backoff if you receive `429 Too Many Requests`.

## Errors

Handle HTTP status codes and error bodies.

| Status | Meaning                                     |
| -----: | ------------------------------------------- |
|    200 | Success                                     |
|    400 | Bad request. Fix parameters or syntax.      |
|    401 | Unauthorized. Check or refresh token.       |
|    403 | Forbidden. Insufficient permissions.        |
|    404 | Not found.                                  |
|    409 | Conflict.                                   |
|    429 | Too many requests. Apply backoff and retry. |
|    500 | Server error. Retry with backoff.           |
|    503 | Service unavailable. Retry with backoff.    |

## Endpoints

### List Walmart purchase orders

**GET** `/v3/walmartOrders`

Returns Walmart POs for the authenticated supplier. Results are restricted to the calling supplier’s data.

#### Query parameters

| Name                             | Type      | Description                                               |
| -------------------------------- | --------- | --------------------------------------------------------- |
| `supplierId`                     | string    | Supplier identifier                                       |
| `hostPurchaseOrderId`            | string    | Host PO ID.                                               |
| `type`                           | string    | PO type. Example: `03` for buyer generated (domestic).    |
| `purchaseOrderStatus`            | string    | High-level PO status. Example: `cancelled`.               |
| `purchaseOrderSupplyChainStatus` | string    | Supply chain status. Example: `received`.                 |
| `createdAfter`                   | date-time | ISO 8601. Filter POs created on or after this timestamp.  |
| `createdBefore`                  | date-time | ISO 8601. Filter POs created on or before this timestamp. |
| `mustArriveByDateAfterDate`      | date-time | ISO 8601. Filter by must-arrive-by date on or after.      |
| `mustArriveByDateBeforeDate`     | date-time | ISO 8601. Filter by must-arrive-by date on or before.     |
| `limit`                          | integer   | Max POs per page. Up to 100.                              |
| `nextCursor`                     | string    | Cursor from previous response to fetch the next page.     |

#### Sorting

* Results are ordered from most recent to oldest based on `createDate`.

#### Pagination

* The response includes a `purchaseOrdersListMeta` object with `totalCount`, `limit`, and `nextCursor`.
* Send a follow-up request with `nextCursor` to get the next page.

#### Example request (list today’s orders)

```bash
curl -X GET   'https://api-gateway.walmart.com/v3/walmartOrders?createdAfter=2024-01-01T00:00:00Z&limit=100'   -H 'wm_sec.access_token: <ACCESS_TOKEN>'   -H 'WM_QOS.CORRELATION_ID: 5f6b2f8a-3a6e-44bd-8e0f-75c1d7f0f9a0'   -H 'WM_CONSUMER.CHANNEL.TYPE: <YOUR_CHANNEL_ID>'   -H 'accept: application/json'
```

#### Example request (filter by supplier)

```bash
curl -X GET   'https://api-gateway.walmart.com/v3/walmartOrders?supplierId=123456789&limit=50'   -H 'wm_sec.access_token: <ACCESS_TOKEN>'   -H 'WM_QOS.CORRELATION_ID: 0d3d6a1b-3e5e-4d6a-9c2b-2f0c7e7b1e22'   -H 'WM_CONSUMER.CHANNEL.TYPE: <YOUR_CHANNEL_ID>'    -H 'accept: application/json'
```

#### Example response (truncated)

```json
{
  "purchaseOrdersListMeta": {
    "totalCount": 200,
    "limit": 100,
    "nextCursor": "123456789"
  },
  "purchaseOrders": [
    {
      "hostPurchaseOrderId": "4500123456",
      "supplierId": "123456789",
      "createDate": "2024-01-01T10:15:00Z",
      "purchaseOrderStatus": "open",
      "purchaseOrderSupplyChainStatus": "inTransit"
    }
  ]
}
```

### Retrieve a single purchase order

**GET** `/v3/walmartOrders/{purchaseOrderId}`

Returns the full details for a single PO, including line items, costs, and line status.

#### Path parameter

| Name              | Type   | Required | Description                 |
| ----------------- | ------ | -------: | --------------------------- |
| `purchaseOrderId` | string |      Yes | Walmart host PO identifier. |

#### Optional query parameters

| Name         | Type   | Description                                                      |
| ------------ | ------ | ---------------------------------------------------------------- |
| `supplierId` | string | Filter to the calling supplier when multi-entity creds are used. |

#### Example request

```bash
curl -X GET   'https://api-gateway.walmart.com/v3/walmartOrders/4500123456'   -H 'wm_sec.access_token: <ACCESS_TOKEN>'   -H 'WM_QOS.CORRELATION_ID: 9a7d6b58-4f12-4c3a-9b65-2c1a7a0f9c30'.   -H 'WM_CONSUMER.CHANNEL.TYPE: <YOUR_CHANNEL_ID>'   -H 'accept: application/json'
```

#### Example response (truncated)

```json
{
  "hostPurchaseOrderId": "4500123456",
  "supplierId": "123456789",
  "createDate": "2024-01-01T10:15:00Z",
  "type": "03",
  "purchaseOrderStatus": "open",
  "lines": [
    {
      "lineNumber": 1,
      "itemNumber": "000000123",
      "description": "Sample item",
      "orderedQuantity": { "unitOfMeasure": "EA", "measurementValue": 12 },
      "unitCost": { "currencyUnit": "USD", "currencyAmount": 5.25 },
      "lineStatus": "open"
    }
  ]
}
```

## Examples of common queries

* Today’s orders: set `createdAfter` to today at `00:00:00Z`.
* Orders for a specific supplier: set `supplierId=123456789`.
* Delivered to DC or store: set `purchaseOrderSupplyChainStatus=received`.
* Cancelled orders: set `purchaseOrderStatus=cancelled`.
* Manually generated orders: set `type=03`.

## Security and privacy

* Do not include PII in URLs or logs.
* Use HTTPS for all requests.
* Rotate and protect access tokens and secrets.