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.

Header	Type	Required	Description
`wm_sec.access_token`	string	Yes	Access token from the Token API.
`WM_QOS.CORRELATION_ID`	string	Yes	Unique ID per request. Use a UUID.
`WM_SVC.NAME`	string	Yes	Your Walmart service name.
`Accept`	string	Yes	`application/json`

If provided during onboarding, include WM_CONSUMER.CHANNEL.TYPE.

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)

curl -X GET 'https://marketplace.walmartapis.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_SVC.NAME: <YOUR_SERVICE_NAME>' -H 'Accept: application/json'

Example request (filter by supplier)

curl -X GET 'https://marketplace.walmartapis.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_SVC.NAME: <YOUR_SERVICE_NAME>' -H 'Accept: application/json'

Example response (truncated)

{ "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

curl -X GET 'https://marketplace.walmartapis.com/v3/walmartOrders/4500123456' -H 'WM_SEC.ACCESS_TOKEN: <ACCESS_TOKEN>' -H 'WM_QOS.CORRELATION_ID: 9a7d6b58-4f12-4c3a-9b65-2c1a7a0f9c30' -H 'WM_SVC.NAME: <YOUR_SERVICE_NAME>' -H 'Accept: application/json'

Example response (truncated)

{ "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.