---
updatedAt: 2026-07-30T22:32:10.000Z
---

# MCS order tracking APIs

You can use the order tracking APIs listed in this section to track mock order status progression.

## Base URL

| Environment | URL                                              |
| ----------- | ------------------------------------------------ |
| Sandbox     | <https://sandbox.walmartapis.com/v3/fulfillment> |
| Production  | <https://api.walmart.com/v3/fulfillment>         |

# Get fulfillment order status

Retrieves fulfillment status updates for an order from submission through delivery. This API validates that the account has the requested sales channel via `GET-STATUS-V1-MOCKER-REQUEST-VALIDATION`.  It builds an internal status request using the account context, `orderNumber`, and `orderChannelId`. Do not send `orgId`.

## Endpoint

```Text bash
GET https://sandbox.walmartapis.com/v3/fulfillment/orders-fulfillments/status
```

## Sample request

```Text cURL
curl -X GET "https://sandbox.walmartapis.com/v3/fulfillment/orders-fulfillments/status" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "WM_SANDBOX: v2" \
  -H "martId: 202" \
  -H "buId: 0"
```
```Text Python
import requests

url = "https://sandbox.walmartapis.com/v3/fulfillment/orders-fulfillments/status"
params = {"orderNumber": "SO123", "orderChannelId": "ORDER_CHANNEL_ID"}
headers = {
    "Authorization": "Bearer <ACCESS_TOKEN>",
    "martId": "202",
    "WM_SANDBOX": "v2",
    "buId": "0",
    "Accept": "application/json",
}

response = requests.get(url, headers=headers, params=params, timeout=30)
response.raise_for_status()
print(response.json())
```

## Success response (200 OK)

```Text JSON
{
  "status": "OK",
  "header": null,
  "payload": {
    "orderNumber": "SO123",
    "orderChannelId": "ORDER_CHANNEL_ID",
    "orderPlacedTime": "2025-10-15T12:34:56Z",
    "orderStatus": "SHIPPED",
    "orderItems": [
      {
        "sellerLineId": "1",
        "sku": "SKU-1",
        "qty": { "unitOfMeasure": "EACH", "measurementValue": 1 },
        "lineStatus": "SHIPPED"
      }
    ],
    "shipments": [
      {
        "shipmentId": "SHIP123",
        "carrier": "CarrierName",
        "trackNumber": "1Z9999999999999999",
        "events": [
          { "eventTime": "2025-10-16T08:00:00Z", "status": "OUT_FOR_DELIVERY" },
          { "eventTime": "2025-10-16T15:30:00Z", "status": "DELIVERED" }
        ]
      }
    ]
  },
  "errors": []
}

```

## Error response

If the order cannot be found, returns `400 Bad Request` with error code `OS_NOT_FOUND_ERROR`.

# Mock order status progression

In the sandbox environment, mock orders progress through fulfillment status automatically based on the strategy selected per request in the order number prefix. This affects the values returned by the [Get Fulfillment Order Status ](/docs/order-tracking-apis#get-fulfillment-order-status) API.

The service determines which progression strategy to use for each request by examining the order number prefix.

* Time-based strategy - If the `customerOrderNo` is null, blank, or does not begin with a recognized status keyword time-based strategy is used.
* Prefix-based strategy - If `customerOrderNo` starts with one of the following keywords: `SUBMITTED`, `ACKNOWLEDGED`, `SHIPPED`, or DELIVERED prefix-bases strategy is used.

## Time-based strategy

When the customerOrderNo has no status or keyword, the order status is advanced based on elapsed minutes since order creation.

**Rules:**

* After approximately 60 minutes: status advances to at least `Acknowledged` or `Processing`.
* After approximately 300 minutes: status advances to `Shipped`.
* After approximately 600 minutes: status advances to `Delivered`.
* Statuses only move forward — once` Cancelled`, the order remains in that state.

This approach simulates a realistic timeline of order progression during sandbox testing.

## Prefix-based strategy

When the `customerOrderNo` begins with a status keyword, the prefix is used to determine how far the order should progress.

**Rules:**

* The service finds the last matching status keyword in the order number using the sequence<br />SUBMITTED → ACKNOWLEDGED → SHIPPED → DELIVERED.
* It compares the current internal `statusDescription` against this ordered list:<br />Fulfillment Request Submitted → PO Created → Shipped → Delivered.
* If the current status is behind the prefix-implied target, the order is advanced one step forward.
* If the current status is equal to or ahead of the prefix, no change occurs.
* Cancelled lines are never advanced.

These strategies transform the in-memory OS response just before building the outward `FulfillmentServiceResponse`, ensuring deterministic testable behavior for status reads.

## Return order status in order tracking

When return orders exist for a given order, the Get Fulfillment Order Status API response includes return-related information.

* Order lines with active returns include additional `orderLineQuantityInfo` entries:
  * `PROCESSING_RETURN`: For items in `RETURN_INITIATED` or `RETURN_IN_TRANSIT`
  * `RETURNED`: For items in `DELIVERED_AT_RETURN_CENTER` or `RETURN_RECEIVED`

* Partial returns are reflected accurately. For example, if 3 items were delivered and 1 was returned, the response returns: `DELIVERED`: 2, `RETURNED`: 1

* The overall order status aggregates return quantities in its computation.

For more information on creating and managing returns, refer to <Anchor target="_blank" href="/us-marketplace/docs/return-order-apis">MCS return order APIs.</Anchor>