Walmart Fulfillment Services (WFS)

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:

Note: You can either set up items with the WFS item spec, or convert existing items with the WFS conversion spec. Select either Option 1 or Option 2.

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

There is a new requirement to set up items. You must indicate item Sale Restrictions by geographic location: State or Zip Code (also known as “State Restrictions). If there are no restrictions, you can set the Restriction Type to “None.” The updated specs provide a StateRestrictions section to provide state code or zip code for all geographic areas that an item cannot be sold.

Provide all States or Zip codes where your product should not be sold for legal or commercial reasons. You have an obligation to notify Walmart of any States where laws, regulations, ordinances etc. prohibit or restrict your product from being sold. Specify items restricted for sale in state or zip code due to laws preventing sale in that locality with StateRestrictionsText ‘Illegal for sale.’

At your discretion, you may also specify any States where you prefer not to have your product sold for commercial reasons. Specify StateRestrictionsText ‘Commercial.’

How state vs zip code restrictions are applied

A state restriction on a product will restrict that product from being sold anywhere within the specified State.

A Zip code restriction will only restrict that product from that Zip Code within a particular State

IMPORTANT: If you are only limiting sale by zip codes, do not add the state code. Once state code is added to restrictions, this will make all zip codes in that state restricted for item sale.

Field Name	Acceptable Values
StateRestrictionsText	Commercial, Illegal for sale, None
states	All US State codes (e.g. AL, AK, AZ, etc.)
zipCodes	Any 5-digit US Zip Code.

To set state restrictions for an item

You need to use the Bulk item setup (Multiple) API with the feedtype=MP_WFS_ITEM.

1. Set states or zip codes that are restricted for item sale. Provide the state codes for the states you want to prohibit sale of that item.
   For example, to set State Restrictions for California and Arkansas, provide “states” : “CA, AR” in your request payload.
2. Provide the reason for the restriction. Set StateRestrictionsText to either ‘Commercial’ ‘Illegal for sale’ or ‘None’

For example, to set Commercial restrictions for California and Arkansas, and Illegal for Sale in Texas and Pennsylvania set State Restrictions:

“sku”: “JE-ICF1-TR6P”, “stateRestrictions”: [ {“stateRestrictionsText“: “Commercial“, “states“: “CA,AR“ }, {“stateRestrictionsText“: “Illegal for Sale“, “states“: “TX,PA“ } ],

To view all example payload requests, see Request Samples in: Bulk item setup (Multiple) API Reference.

To update state restrictions for an item

To update or delete sales restrictions that you already have set for items, you need to use the Bulk item setup (Multiple) API with the feedtype=MP_MAINTENANCE.

IMPORTANT: Any change to state restrictions represent an override of the entire list of state restrictions that were set with initial Item setup API call. Make sure to provide the complete list of all state restrictions again with any update or delete to an individual change in the request payload.

To update a state restriction

If you want to make a change to an item’s state restrictions that were set up, you need to override the entire list of state restrictions set during initial item set up process.

1. Send API call to Bulk item setup (Multiple) API with the feedtype=MP_MAINTENANCE.
2. Specify StateRestrictionsText either ‘Commercial,’ ‘Illegal for sale,’ or ‘None’ for the new restriction, and provide the state code or zip code.
3. In request payload, make sure to provide complete list of state restrictions again. Each call to the Bulk item setup API overrides the entire previous list of restrictions.

To delete a state restriction

1. Send API call to Bulk item setup (Multiple) API with the feedtype=MP_MAINTENANCE.
2. Set state restrictions attribute to “None” in the payload request. You do not need to specify State code or Zip code. For example: stateRestrictionsText“: “None”
3. In request payload, make sure to provide complete list of state restrictions for all the restrictions you want to keep. Each call to the Bulk item setup API overrides the entire previous list of restrictions.

List of State Codes

This is a list of all US state codes to specify for the states field.

State Name	State Code	State Name	State Code
Alabama	AL	New Mexico	NM
Alaska	AK	New York	NY
Arizona	AZ	North Carolina	NC
Arkansas	AR	North Dakota	ND
California	CA	Ohio	OH
Colorado	CO	Oklahoma	OK
Connecticut	CT	Oregon	OR
Delaware	DE	Pennsylvania	PA
Florida	FL	Rhode Island	RI
Georgia	GA	South Carolina	SC
Hawaii	HI	South Dakota	SD
Idaho	ID	Tennessee	TN
Illinois	IL	Texas	TX
Indiana	IN	Utah	UT
Iowa	IA	Vermont	VT
Kansas	KS	Virginia	VA
Kentucky	KY	Washington	WA
Louisiana	LA	West Virginia	WV
Michigan	MI	Wisconsin	WI
Maine	MN	Wyoming	WY
Mississippi	MS	District of Columbia	DC
Missouri	MO	American Somoa	AS
Montana	MT	Federated States of Micronesia	FM
Nebraska	NE	Guam	GU
Nevada	NV	Marshall Islands	MH
New Hampshire	NH	Northern Mariana Islands	MP
New Jersey	NJ	Puerto Rico	PR
Palau	PW	Virgin Islands	VI

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 WFS Item spec (MP_WFS_ITEM_SPEC_4.1.json) to set up and convert items for WFS items in one setup process.

To get the WFS Item JSON spec, see Item Specs v4 in the Items guide.

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.

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.

About required attributes

The first 148 lines of the JSON spec are all required. Most of the required attributes are indicated as “required” in the spec file. However, there is a nuance for the Trade Item object, that has four optional attributes. At least one of them is required.

Trade Item Required Attributes

In the Trade Item Section, at least one of the following attributes is required: each, inner pack, case, or pallet.

You can choose any of the four attributes, but at least is required. Under TradeItem object, you can find each, innerPack, case, and pallet. This example identifies the four TradeItem attribute groups, with the name of the attributes shown only. The entire section of the attributes is required, this example marks with an ellipsis where nested information is not shown.

"TradeItem": {
   "$schema": "http://json-schema.org/draft-04/schema#", 
     "type": "object", 
     "properties": { 
      . . .
               "each": { 
      . . .
               "innerPack": { 
      . . .
               "case": { 
      . . .
               "pallet": { 

Create an Inbound Purchase Order

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

All items must be WFS-eligible before you can create an IO to send inventory to WFS. 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 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.

Note: If you have not yet set up your items, you can take advantage of the full Item + WFS Json spec to convert and upload items in one process. See Set up Items for WFS. To download the spec, see: Item Object v4.0.

Item Conversion Overview

Full details are provided in subsequent sections, but here is an overview of the item conversion process to become WFS-eligible items:

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 the Convert Items to WFS API. Use the OMNI_WFS feed type.

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.

Step 1: Download WFS Item Conversion JSON Schema

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

Step 2: (Optional) create an inbound PO

Optionally, you can create an inbound Purchase Order (PO). Download and extract the Inbound Purchase Order JSON Schema: InboundPurchaseOrderSchema.zip.

Step 3: Call Convert Items for WFS API

After you’ve extracted the WFS Item conversion spec, you can Call POST Convert Items to WFS API. Default feedType is OMNI_WFS, (e.g. https://marketplace.walmartapis.com/v3/feeds?feedType=OMNI_WFS).

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

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.