Call this endpoint to create an Inbound Order (IO) after you convert your item for Walmart Fulfillment Services (WFS).

Note: This page describes an example using only the required parameters and inputs to create an inbound shipment order to WFS. For a full list of customization options and additional capabilities, refer to the Marketplace WFS API Reference.

Endpoint

post https://marketplace.walmartapis.com/v3/fulfillment/inbound-shipments

Overview

Ensure that each physical shipment to WFS has an inbound shipment record. create an inbound shipment the includes the ID for the shipment request, return address, shipment quantity and the item's SKU. Optionally, you can set up Walmart's WFS prep service to have your items packaged and labeled for a lower cost. You can also choose the use Walmart's Inventory Transfer Service (ITS) to distribute your inventory to multiple fulfillment centers across the country.

WFS Prep Services

WFS Prep Services is an optional addOnService using which you can outsource your inbound inventory preparation to WFS for a small fee. You can set a preference for each UPC on your IO (currently, only the Item Labeling service is offered).

1. After you request a prep service, the system will notify your assigned WFS fulfillment center.
2. When your items arrive, Walmart will complete your requested add-on services (such as item labeling) and make the items available on Walmart.com.

For more information about WFS prep service, refer to WFS Prep Services.

Inventory Transfer Service

Inventory Transfer Service (ITS) is an optional addOnService using which you can utilize WFS transfer stations to distribute inventory across Walmart's network for a small fee. Using ITS, you can conveniently ship your sortable inventory to one transfer station compared to multiple fulfillment centers via self-distribution.

1. Using the Inbound Preview API to preview the estimated price and shipping destinations is optional for using Inventory Transfer Service (ITS) and self-distribution.
2. Using the Create Inbound Shipment API, you can use the InventoryTransferService to choose Y for ITS and N for self-distribution. You have the flexibility to choose for every inbound shipment.
3. If you select Y, your sortable items will be assigned to one WFS transfer station as its shipping destination. Otherwise, your sortable items will be assigned to be shipped to multiple fulfillment centers. If a response is not provided, this parameter will be N by default.

For more information about ITS, refer to WFS Inventory Transfer Service: Overview.

How to prevent common errors

• Ensure you have filled in all required fields in the API request call. The IO cannot be created if the required parameters are missing.
• Verify productId contains the correct number of digits depending on which item code you specified for productType: GTIN.
• Make sure the shipmentId is unique for this IO request. If it was used previously, the API 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 has been created and the shipping label and tracking information have been provided. WFS is waiting for the Shipment 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 documents in advance.
• Receiving in progress – Indicates that the shipment has been delivered to the warehouse and the inventory has been filled.
• Closed – Indicates that WFS has fulfilled the IO.
• Canceled – Indicates shipment was canceled and will not be sent to the WFS warehouse.

Sample request

This sample request shows how to create an inbound shipment.

curl --request POST \ --url https://marketplace.walmartapis.com/v3/fulfillment/inbound-shipments \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --data '
{ "inboundServices": { "inventoryTransferService": "Y" }, "returnAddress": { "addressLine1": "Address line 1", "addressLine2": "", "city": "Name of city", "stateCode": "Two-retter stayr code", "countryCode": "USA", "postalCode": "12345" }, "orderItems": [ { "nonSortItem": true, "productId": "00894147009695", "productType": "GTIN", "sku": "WILL-SL969", "itemDesc": "Blue jeans", "itemQty": 10, "vendorPackQty": 10, "innerPackQty": 1, "expectedDeliveryDate": "2020-11-21T00:00:00.000Z", "addOnServices": [ { "serviceType": "LABEL" } ] } ], "inboundOrderId": "8778881015027"
}
'

import requests url = "https://marketplace.walmartapis.com/v3/fulfillment/inbound-shipments" headers = { "Accept": "application/json", "Content-Type": "application/json",
} json_data = { "inboundServices": { "inventoryTransferService": "Y" }, "returnAddress": { "addressLine1": "Address line1", "addressLine2": "", "city": "Name of city", "stateCode": "Two-letter US State", "countryCode": "USA", "postalCode": "12345" }, "orderItems": [ { "nonSortItem": True, "productId": "00894147009695", "productType": "GTIN", "sku": "WILL-SL969", "itemDesc": "Blue jeans", "itemQty": 10, "vendorPackQty": 10, "innerPackQty": 1, "expectedDeliveryDate": "2020-11-21T00:00:00.000Z", "addOnServices": [ { "serviceType": "LABEL" } ] } ], "inboundOrderId": "8778881015027"
} response = requests.post(url, headers=headers, json=json_data)
print(response.status_code)
print(response.text) 

Sample response

Successful inbound shipment response

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

{ "status": "OK", "payload": [ { "shipmentId": "0000966GDM", "shipToAddress": { "addressLine1": "Address line 1", "city": "Name of city", "stateCode": "Two-letter state code", "countryCode": "US", "postalCode": "12345" }, "shipmentItems": [ { "vendorSku": "WILL-SL969", "itemQty": 10 } ], "expectedDeliveryDate": "2020-11-21T00:00:00.000Z" } ]
}

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": {} } ] }

FAQ

• How does WFS decide which fulfillment center to send my inbound order?
  WFS has an allocation engine to determine network capacity for order fulfillment 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 might change the expected delivery date depending on the Fulfillment center capacity. You might see a different entry in the response for expectedDeliveryDate than what you provided in the request.
• What should I do when there are IO errors?
  Check for IO errors and resubmit the IO request. Call the Inbound Shipment Errors API to check for errors. After correcting errors in the Inbound Order, resubmit the request using the same Inbound Order ID inboundOrderId.

Result

If successful, the API returns 200 OK with a JSON body that includes a header object, an array of orders, current status, shipments with carrier, tracking, and quantity details.