Walmart Fulfillment Services

Walmart Fulfillment Services (WFS) offers sellers another tool to grow their business and reach more customers by fulfilling orders at Walmart Fulfillment Centers (FC)s. Order fulfillment with WFS is fast, at a low-cost to sellers.

Sellers can store their inventory at Walmart FCs and get access to Walmart’s omni channel capabilities such as our Free & Easy Returns program, that provides a competitive advantage that no other third-party service can offer.

WFS allows sellers to increase sales by offering free 2-day shipping, and get Buy Box prominence with the 2-Day tag to their items.

To learn the advantages to using WFS, see: Walmart Fulfillment Services.

WFS Inbound Order and Shipment Workflow

To create new inbound orders (IO)s and ship inventory to fulfillment centers, there is a new process.

WFS API Workflow

To set up items for WFS and create Inbound Orders (IO) to ship inventory to WFS fulfillment network, use the WFS fulfillment APIs in this order:

1. Set up item for WFS. Call Convert items for WFS API: POST /v3/feeds?feedType=OMNI_WFS
2. Create an Inbound Order (IO). Call Create inbound Shipment API: POST /v3/inbound-shipments?sellerId={sellerId}
3. Check for errors in the IO. Call Inbound Shipment Errors API: GET /v3/inbound-shipment-errors?{}
4. Get IO shipment-level details. Call Get Shipments API: GET /v3/inbound-shipments
5. Get the IO SKU-level item details from fulfillment center. Call Inbound Shipment Items API: GET /v3/shipment-items
6. Update shipment quantities prior to delivery. Call Update Shipment Quantities API: GET /v3/shipment-quantities?sellerId={sellerId}
7. Request shipping labels. Call Create Inbound Shipment Label API: GET /v3/fulfillment/label/{shipmentId}
8. Provide the shipment tracking information. Call Update Shipment Tracking API: POST /v3/shipment-tracking?sellerId={sellerId}
9. Cancel an IO. Call Cancel Inbound Shipment API:
   DELETE /v3/inbound-shipments/{inboundOrderId}?sellerId={sellerId}

All items must be WFS-eligible before you can create an IO to send inventory to WFS.

You can convert existing Marketplace items to be WFS eligible. Once you’ve created a Marketplace item, each item must be converted to WFS by providing additional details that are not required during the item setup process.

To learn how to convert your item to be eligible for Walmart Fulfillment Services, see Seller Help: Convert your items to WFS.

For more details about hazmat item compliance requirement, see Seller Help: Hazardous Items – What to do if your item is considered Hazmat.

This section provides two options: Set up items for WFS, or Convert items to WFS.

Set up items for WFS

All items must be WFS eligible before you can create an IO to send inventory to WFS. If you haven’t created your items yet, you can use the Item Spec v4.1 to set up your items for WFS in one step.

See Set up items in the Items guide.

New requirement: Restrict item sale by geographic location

There is a new requirement for setting up or converting items to WFS to indicate item Sales Restrictions by geographic location: State or Zip Code. If there are no restrictions, you can set the Restriction Type to “None.”

For more details about the State Restrictions attribute and its usage, see Restrict item sale by state or zip code in the Items guide.

Convert items to WFS

You can also convert existing Marketplace items to be WFS-eligible. After You create a Marketplace item, it can be converted to WFS. Provide the additional details required for WFS that are not required during the initial item set up process.

To convert item to be eligible for WFS, use POST Convert Items for WFS API.

Prerequisite: Download WFS Item Conversion JSON Schema

Download the WFS Item conversion JSON schema:   WFS_Convert_Schema_v1.3.json

Item Conversion Checklist

To start the item conversion process:

1. Download and extract the WFS conversion spec to either convert your item to WFS, or create an inbound purchase order.
2. (Optional): If you haven’t created your items yet, you can use the new Item Spec v4.1 to set up your items for WFS in one step. See Set up and manage items in the Items guide.
3. Call POST v3/feeds to Convert Items to WFS. Default feedType is OMNI_WFS, (e.g. https://marketplace.walmartapis.com/v3/feeds?feedType=OMNI_WFS).

Create an Inbound Purchase Order

Download and extract the Inbound Purchase Order JSON Schema: InboundPurchaseOrderSchema.zip.

Create new items for WFS

You can also take advantage of the full Item + WFS JSON spec to convert and upload items in one setup process.

To create new items that are WFS-eligible in one process, use the new full spec forWalmart and WFS. To learn more about the new Item Spec v4.0, and how to set up items, see: Item Object v4.0.

After you convert your item for fulfillment via Walmart Fulfillment Service (WFS) you can create an Inbound Order (IO).

To create an Inbound Shipment Order (IO), Call Create inbound Shipment API: POST /v3/inbound-shipments

Specify all required request parameters

You need to provide information in the request to create the IO to avoid any errors. Requests require these parameters:

• Create an ID for the shipment request – inboundOrderId
• Provide a return address to return shipment if needed – returnAddress
• Updated shipment quantity – updatedShipmentQty
• Seller’s item ID – sku

How to prevent common errors

• Make sure that you have filled in all required fields in the API request call. If required parameters are missing, the IO cannot be created.
• Verify productId contains correct number of digits depending on which item code you specified for productType: EAN, UPC or GTIN.
• Make sure the shipmentId is unique for this IO request. If it was used previously, it will return errors.

Shipment Statuses

When you submit your request to create an Inbound Order, you will receive one of these order statuses in the response:

• Pending Shipment Details – Shipment is created, but still requires a shipment label or tracking information.
• Awaiting Delivery – Indicates that the shipment is created, shipping label and tracking are provided. WFS is waiting for Shipments to arrive at the warehouse. Shipments remain with Awaiting Delivery status until the first unit has been received. If the carrier states that your shipment has been delivered, but WFS indicates “Awaiting Delivery” it is likely due to backups at the inbound dock. To avoid backups, always schedule freight appointments with required document in advance.
• Receiving in Progress – Indicates the shipment is delivered to the warehouse and inventory is being filled.
• Closed – Indicates that WFS has fulfilled the IO.
• Cancelled – Indicates shipment was cancelled, and will not be sent to the WFS warehouse.

Example: Inbound Shipment Request

A successful request to create an inbound shipment:

{
  "inboundOrderId": "32414541542",
  "returnAddress": {
    "addressLine1": "860 W California Ave",
    "addressLine2": "",
    "city": "Sunnyvale",
    "stateCode": "CA",
    "countryCode": "US",
    "postalCode": "94086"
  },
  "orderItems": [
    {
      "productId": "231263112312",
      "productType": "UPC",
      "sku": "VV-631",
      "itemDesc": "Blue jeans",
      "itemQty": 123,
      "vendorPackQty": 123,
      "innerPackQty": 1,
      "expectedDeliveryDate": "2020-05-19T00:00:00.000Z"
    },
    {
      "productId": "1213223423131",
      "productType": "EAN",
      "sku": "VV-234",
      "itemDesc": "Google mini",
      "itemQty": 22,
      "vendorPackQty": 2,
      "innerPackQty": 11,
      "expectedDeliveryDate": "2020-05-25T00:00:00.000Z"
    }
  ]
}

Example: Inbound Order Response

Upon success, the API returns response with status “OK.”

HTTP/1.1 200 OK
Content-Length: xxx
Content-Type: application/json; charset=utf-8

{
  "status": "OK",
  "payload": [
    {
      "shipmentId": "2312355646",
      "shipToAddress": {
        "addressLine1": "860 W California Ave",
        "addressLine2": "",
        "city": "Sunnyvale",
        "stateCode": "CA",
        "countryCode": "US",
        "postalCode": "94086"
      },
      "shipmentItems": [
        {
          "sku": "VV-631",
          "itemQty": 123
        }
      ]
    }
  ]
}

Example: Inbound Shipment Response with Errors

If the API request fails, you will get the errors returned with FAIL status:

HTTP/1.1 400 BAD REQUEST
Content-Length: xxx
Content-Type: application/json; charset=utf-8
Error Response  
{
  "status": "FAIL",
  "errors": [
    {
      "code": "400.INBOUND_SHIPMENTS.100",
      "field": "vendorSku",
      "description": "vendorSku cannot be null or empty",
      "severity": "ERROR",
      "category": "REQUEST",
      "errorIdentifiers": {}
    }
  ]
}

How does WFS decide which fulfillment center to send my Inbound Order?

WFS has an allocation engine to determine network capacity for order fulfillments, and sends your Inbound Order to the FC that can handle the shipment request.

Why is there a different expected delivery date in the response?

WFS may change the expected delivery date depending on Fulfillment center capacity. You might see a different entry in the response for expectedDeliveryDate than what you provided in the request.

Check for IO errors and resubmit IO request

To check for errors, call the Inbound Shipment Errors API.

After you correct any errors in the Inbound Order, resubmit the request with the same Inbound Order ID: inboundOrderId.

The next step after you create an IO is to check for errors. You can avoid most errors by doing a robust API integration. But if you encounter errors, you can re-submit the request to create the IO with the same Inbound Order ID.

To verify IO has no errors, call /v3/inbound-shipment-errors and specify the shipmentID you created when you called the Create Inbound Shipment API.

Possible Inbound Order Errors

• SKU is not in WFS catalog – Seller must make item eligible for WFS. You need to convert all SKUs to add them to the WFS catalog. See Convert Items for WFS.
• Missing required information – Indicates missing value in the CVS file for one of the required fields. Repeat the Create an IO process. See Create Inbound Shipment.
• Invalid Product ID – Incorrect number of digits in the productId.
• Duplicate Inbound Order ID – shipmentId exists for previous order.
• Duplicate Product ID – productId is provided multiple times in the CVS file. Make sure to remove duplicate entries for productId in your request to create the IO.

Errors deleted after you resubmit the IO

After you resubmit an Inbound Order that previously had errors, the historical errors for the Inbound Order ID are removed and no longer accessible.

After Sellers create an Inbound Order successfully, the response from Create Inbound Shipments API will tell whether the order can be sent in a single shipment to one WFS fulfillment center or needs to be split into multiple shipments to different fulfillment centers.

To retrieve the Shipment level info, please call the Get Inbound Shipments API to receive specific details.

To request the IO shipment details, call GET /v3/inbound-shipments{shipmentId} and provide query parameters to specify the details you want to see for the shipment.

You can search for these shipment details, by passing the corresponding query parameter in your API call:

• Number of Inbound Orders to be returned – offset
• Get the ID for the shipment request –inboundOrderId
• Get the ID for the shipment – shipmentId
• Get the status of the IO shipment – status
• Start date for IO creation – fromCreateDate and toCreateDate

Note: to see item-level shipment details, see Request IO Item details.

Receive shipping details

The response returns this information about the IO shipment request:

• ID for the IO request —inboundOrderId
• Shipment ID- shipmentId
• Address for sellers to send their shipment – shipToAddress
• Status of the Shipment – status
• Shipment creation date – createdDate
• Total units in the shipment – shipmentUnits
• Total units received by the FC – receivedUnits
• Seller-provided expected delivery date – expectedDeliveryDate
• Actual Delivery Date for FC to deliver the item based on network capacity – updatedExpectedDeliveryDate
• Shipment Tracking Number – trackingNo
• Shipment Carrier Name – carrierName

For detailed descriptions, see API Reference for Get Shipments.

Sellers may need to get specific shipment details for a SKU within an Inbound Order.

To get these item details, call the GET Inbound Shipment Items API to retrieve Inbound Order item-level details. Specify the shipmentId as a query parameter, and it will return all of the information about the items within that IO.

Item details provided by Inbound Shipment Items API:

• Inbound Order ID
• Shipment ID
• UPC and EAN
• Vendor SKU
• Item Description
• Item Quantity
• Vendor Pack Quantity: number of cases
• Inner Pack Quantity: number sellable units per case
• Received Quantity
• Damaged Quantity
• Fill Rate
• Seller-provided Expected Delivery Date
• WFS Updated Expected Delivery Date
• Ship Node Name (WFS FC Name) 

If you need to update shipment quantities prior to delivery for an Inbound Order, use the Update Shipment Quantities API.

You can update shipment quantities before the shipment arrives at the Walmart Fulfillment Center.

Ineligible Statuses for Update Quantities API

Shipments with statuses: Receiving in-progress, Closed or Cancelled are not eligible to update quantities with this API.

For each SKU you need to provide new quantities for the shipment.

You can add up to a maximum of 6 units per SKU.

To remove a SKU from a shipment, you can reduce the SKU quantity to zero.

CAUTION: You cannot change all SKU quantities to zero, or it will cancel the entire Inbound Order.

After you create your Inbound Order for WFS, you need to provide shipment tracking information.

For small parcels, provide tracking information including the shipment carrier name (e.g. USPS) and the tracking number.

WFS can then update the expected delivery date to adjust the fulfillment inbound capacity to avoid any receiving delays.

You can call Inbound Shipment Items API to get an update on the expected delivery date.

Send Shipment Tracking Info to WFS

To provide tracking information, use the Update Shipment Tracking API.

Call POST /v3/fulfillment-shipment-tracking and specify these request parameters:

• Inbound Order shipment ID – shipmentId
• Name of the shipment carrier: carrierName
• Tracking number – trackingInfo

Tracking Info  
{
  "shipmentId":"431252355",
  "carrierName":"USPS",
  "trackingInfo":["423154512","145254552355"]
}

Upon success, you will simply receive “OK” status response:

HTTP/1.1 200 OK
Content-Length: xxx
Content-Type: application/pdf;
{
  "status": "OK"
}

If you need to cancel an Inbound Order that you created, you can call the Cancel Inbound Shipment API.

You can cancel an inbound order before the shipment arrives at the WFS fulfillment center. Individual shipments within an Inbound Order may not be cancelled individually, you need to cancel an entire IO.

Note: If the Shipment status is “Receiving in-progress,” “Closed,” or “Cancelled” you cannot cancel it. To verify shipment status, call GET Inbound Shipments API.

To cancel an Inbound Order, call DELETE /v3/fulfillment/inbound-shipments{inboundOrderId} and specify the Order ID inboundOrderId as a URL path parameter.

Example: Successful Order Cancel Response

If the call is successful, you will get status “OK” returned:

HTTP/1.1 200 OK
Content-Length: xxx
Content-Type: application/json; charset=utf-8 
{
  "status": "OK"
}

Example: Failed Cancel Order Response

If the request to cancel an IO fails, you will get errors returned with status:

HTTP/1.1 400 BAD REQUEST
Content-Length: xxx
Content-Type: application/json; charset=utf-8 
{
  "status": "FAIL",
  "errors": [
    {
      "code": "400.INBOUND_SHIPMENTS.100",
      "field": "inboundOrderId",
      "description": "inboundOrderId cannot be null or empty",
      "severity": "ERROR",
      "category": "REQUEST",
      "errorIdentifiers": {}
    }
  ]
}

Once you’ve converted items to WFS, you are ready to start shipping items inbound to Walmart. To do this, you will submit an Inbound Purchase Order. The Inbound Purchase Order details when you expect to ship product, as well as the items and quantities which will be shipped.

Each shipment you send in to WFS should have a corresponding Inbound Purchase Order. In this case, a shipment would be considered a direct truckload, LTL shipment, or set of items shipped via parcel on a given day.

To begin shipping your items to Walmart Fulfillment Service, create your purchase order.

To create an inbound purchase order (PO), call POST v3/fulfillment/inbound-purchase-orders.

Once an Inbound Purchase Order has been submitted (via API or upload through Seller Center), it must be accepted by our system before you can ship your items. This ensures that all necessary information is complete and that each item you intend to ship has been set up and converted to WFS items.

Shipping items to WFS that do not have accepted Inbound Purchase Order will delay receiving at the fulfillment center and may result in chargeback fees. Use this GET Inbound PO API to check the status of your submitted Inbound Purchase Orders.

To check status of your purchase order, call GET /v3/fulfillment/inbound-purchase-orders.