On-request Reports

The On-request Reports API enables you to request item reports immediately about your items for faster retrieval. Now you can request a report at any time, subscribe to notifications that report is ready, and then you can download it.

Report generation time

After you request the report, it takes 15 to 45 minutes to generate, then it is available for download.

Report retention period

Reports that you request are retained for 30 days. You can request the report for 30 days with the request id for the report, you don’t need to request a new one.

Request limit

You can request one report for each report type per hour. Although you can request multiple report types at the same time, you can make a request for each report type only once per hour.

Report request workflow

1. Create a report request with the Create Report Request API. For each request, the system creates a Request ID that the seller uses to track the status of the requested report.
2. Check report request submission status with the Report Request Status API, which returns all details about the report status.
3. Once the report has a status of READY, you can now download the report with the Download Report URL API.
4. (Optional): You can also get a list of all report requests with the Get All Report Requests API. 
5. (Optional): If you set up notifications with Create Subscriptions API: When you receive the notification that the report is ready, you can retrieve it for download with the Download Report URL API.

Diagram: Report Request Workflow

The Item report version 3 is a new report that you can request on-demand. The on-request item report is restructured, with different column names and locations.

Once the report is available, you can download it to return all the information associated with your items that are set up on Walmart’s platform.
On 12 April, 2022, Item report version 3 launched with item variant data. A variant group is a group of individual items that differ by only a few attributes.

On 14 Oct, 2021, Item report version 2 launched with containing repricer data. The Repricer is a new tool that can help sellers enable automatic price adjustments for items in their catalog. The prices are adjusted based on triggers such as the Buy Box offer prices or external site prices depending on the strategy that sellers select and assign to their items.

Note: All example API calls shown assume the Walmart API endpoint: https://marketplace.walmartapis.com

Report Field Descriptions

The CSV report file contains the following fields. The identifiers can be specified by either the seller or Walmart.

Field	Description	Origin
SKU	Unique identifier for the item	Seller
Item ID	Unique Item ID	Walmart
Product Name	Name of the item	Seller
Lifecycle Status	The offer lifecycle status	Walmart
Publish Status	Whether the item is published on Walmart.com	Walmart
Status Change Reason	Reason for status change	Walmart
Product Category	The category of this item. This may differ from what was suggested when the item was ingested	Walmart
Price	The current price of the item	Seller
Currency	The currency of the item price	Seller
Buy Box Item Price	Buy box winner’s item price	Walmart
Buy Box Shipping Price	Buy box winner’s price to ship item	Walmart
MSRP	Manufacturer’s suggested retail price. This is not the price that Walmart customers will pay for your product	Seller
Product Tax Code	This is a seven-digit product tax code that identifies the amount of sales tax that should be collected for individual items	Seller
Ship Methods	Shipping methods available for each item	Seller
Shipping Weight	The weight of the item when packaged to ship	Seller
Fulfillment Lag Time	The number of days between when an item is ordered and when it is shipped	Seller
Fulfillment Type	Specifies the method of fulfilment the SKU is set to. Possible values include WFS Eligible, Walmart Fulfilled, or Seller Fulfilled. WFS Eligible means item has been converted to WFS program, but still being fulfilled by seller.	Walmart
WFS Sales Restriction	Specifies the current WFS-eligible item SKU Sales Restrictions for either a Zip code or State code that is restricted for sale either by reason: Commercial, Illegal for Sale, or None. For more details, see Restrict item sale by state or zip code. Example values: state codes (e.g. CA, TX) or zip codes (e.g. 94112,94546,94568)	Seller & Walmart
WPID	The Walmart Product ID assigned by Walmart to the item when listed on Walmart.com	Walmart
GTIN	The item’s Global Trade Item Number. This may differ from what was suggested when the item was ingested	Walmart
UPC	The item’s Universal Product Code. This may differ from what was suggested when the item was ingested	Walmart
Item Page URL	URL for item page on walmart.com	Walmart
Primary Image URL	URL for primary image	Walmart
Shelf Name	Walmart assigned an item shelf name	Walmart
Primary Category Path	The primary item category path on Walmart.com	Walmart
Brand	Name, term, design or other feature that distinguishes one seller’s product from those of others. This can be the name of the company associated with the product.	Seller
Offer Start Date	Date at which the item becomes visible on Walmart.com	Seller
Offer End Date	Date after which the item will not be visible on Walmart.com	Seller
Item Creation Date	The system timestamp date when an item was created	Walmart
Item Last Updated	The system timestamp date when an item was updated	Walmart
Reviews Count	The total number of customer reviews for the item	Walmart
Average Rating	An average rating number for the item from customers	Walmart
Searchable?	Signifies how easy it is to find an item on Walmart.com	Walmart
Variant Group Id	Unique ID that was created to identify all the items in the variant group	Seller
Primary Variant?	Variant item selected as primary when the group was created	Seller
Variant Grouping Attributes	Variants vary by these attributes in the variant group	Seller
Variant Grouping Values	All values assigned to the variant attributes	Seller
Competitor URL	Competitor’s website URL	Walmart
Competitor Price	Competitor’s item price	Walmart
Competitor Ship Price	Competitor’s price to ship item	Walmart
Competitor Last Date Fetched	Date when the competitor’s data was last fetched	Walmart
Repricer Strategy	The rule based actions that the sellers wishes to assign to their items. e.g. “Beat Buy Box Price” adjusts seller prices to beat the Buy Box Price. “Meet/Beat External Price” adjusts seller prices to meet/beat other site prices	Seller
Minimum Seller Allowed Price	Offer’s floor/lowest price at which the seller is willing to sell it for	Seller
Maximum Seller Allowed Price	Offer’s ceiling/highest price at which the seller are willing to sell it for	Seller
Repricer Status	The last repricing action taken on seller item	Walmart

Step 1: Request the item report

To request an item report, call Create Report Request API.

For example, call v3/reports/reportRequests?reportType=ITEM&reportVersion=v2

Specify values for all required parameters:

• reportType – Specify which report you want to request (e.g. reportType=ITEM).
• reportVersion – Specify report version (e.g. reportVersion=v2).

Upon success, the API call returns a requestID, that you can use to find out if the report is ready for download, and status of the request (e.g. RECEIVED or INPROGRESS). It also returns values for requestSubmissionDate in UTC format: YYYY-MM-DDTHH:mm:ssZ.

You can also set up a Notification to trigger once the report status is READY. To set up a notification, see Notifications.

Apply Filters

Filter helps to reduce the size of report and specify data for exclusion and inclusion in the final downloaded report. As of now, Filters are supported only for ITEM report.

2 categories of filters are supported –

1. Column Filter

Using this filter, columns that are not required can be excluded from the report. 
Note: mandatory columns [SKU,Product Name,Item ID,GTIN,UPC,WPID] can not be excluded.

{
    "excludeColumns":["Average Rating", "Reviews Count", "Shipping Weight", "MSRP", "Fulfillment Lag Time" ]
}

2. Row Filter

Range Filter:

Using this filter, specific rows which contain item details can be selected for inclusion in the final report version. Filters to select specific range of values for data elements in columns can be applied by specifying “from” and/or “to” in the range filter as per the format shown below.

In case of columns with date values, supported format is yyyy-mm-dd. For columns with numeric values, only 0 and positive numbers are supported.

Date Columns where ranges can be specific using range filters are Offer Start Date, Offer End Date, Item Creation Date, Item Last Updated

{
    "rowFilters":[
        {
        "type":"rangeFilter",
        "columnName":"Offer Start Date",
        "from":"2021-07-03"
        },
        {
        "type":"rangeFilter",
        "columnName":"Offer End Date",
        "to":"2021-07-30"
        }
    ]
}

Additionally, report contains columns that support numerical values for Price, Buy Box Item Price, Buy Box Shipping Price, Reviews Count, Shipping Weight, MSRP, Fulfillment Lag Time, Average Rating

{
    "rowFilters":[
        {
        "type":"rangeFilter",
        "columnName":"Price",
        "from": "5",
        "to": "10"
        }
    ]
}

Enum Filter:

Filters can be added on columns to select specific values only to be added in the final report. For example, select all items with publish status as “IN PROGRESS” can be executed using enum filters.
Supported columns for enum filters are:

• Publish Status – [“IN_PROGRESS”,”PUBLISHED”,”SYSTEM_PROBLEM”,”UNPUBLISHED”]
• Lifecycle Status – [“ACTIVE”,”ARCHIVED”,”DRAFT”,”RETIRED”]
• Fulfilment Type – [“Walmart Fulfilled”,”WFS Eligible”,”Seller Fulfilled”]
  Enum Filter snippet

{
    "rowFilters":[
        {
        "type":"enumFilter",
        "columnName":"Publish Status",
        "values":["PUBLISHED", "IN_PROGRESS"]
        }
    ]
}

Step 2: Get report availability status

To find out if the report is ready for download, call Report Request Status API to retrieve report request status. When status is READY, you can download the report. The API can only retrieve details of requests created in the past 30 days.

For example, call v3/reports/reportRequests?{requestId} with the request ID.

Upon success, this call retrieves the status of the specified request ID (e.g. SUBMITTED, INPROGRESS, READY, or ERROR).

Step 3: (Optional) Subscribe to an event notification

To get a notification when the report you request is ready to download, create a Webhook notification. When the report status changes to READY, this triggers the notification.

For steps to subscribe, See Notifications. In addition to other required parameters, make sure to set resourceName to REPORTS, eventType to REPORT_STATUS, eventVersion to V1.

For example:

"resourceName": "REPORTS",
"eventType": "REPORT_STATUS",
"eventVersion": "V1",
"description": "Notification for report status"

Step 4: (Optional) Get a list of all requests

To get a list of all report requests in the last 30 days, call Get All Report Requests API. Request log does not continue to store requests past 30 days.

For example, call /v3/reports/reportRequests directly to retrieve a list of all requests.

(Optional): You can also filter the list with these query parameters:

• reportType – Specify a specific type of report only, for example reportType=ITEM for Item Report.
• requestId – Specify a single request ID to return.
• requestStatus – Request only report requests with one status to be returned: RECEIVED, INPROGRESS, READY, ERROR. For example requestStatus=READY.
• requestSubmissionStartDate – Specify a range of report requests and provide start date.
• requestSubmissionEndDate – Specify a range of report requests and provide end date.

Upon success, it retrieves a list of all reports that were requested with the Create Report Request API. It provides a list of request IDs by request submission date.

Example: Request all Reports that are Ready

If you want to return all current report requests that are currently ready, you can call:

/v3/reports/reportRequests?requestStatus=READY

Step 5: Download the report URL

To download a report you requested, call Download Report URL API and specify the requestID sent by the report status notification, or from a status API call.

For example, call /v3/reports/downloadReport?requestId={requestId}

Upon success, you receive the URL to download the report along with the URL expiration time:

• downloadURL – the URL to download the report.
• downloadURLExpirationTime – the download URL expiration time.

To avoid errors, make sure to check that these situations don’t apply to your request:

• The request has expired. In this case, the Report is no longer available.
• If the report is not available yet, check to see that status is not INPROGRESS.
• Could be either system error, or data errors.
• If the requestId is invalid. Make sure you have the correct ID, or that it hasn’t expired after 30 days.

Troubleshooting and Error Codes

If you get failures, here are some hints for how to solve these possible errors. Notice there are several reasons why you might get INVALID_REQUEST_PARAM error, depending on which API you call, and which parameters are required for that API.

Error Code	Description
SYSTEM_ERROR	There is an error in the system. Please wait and try again later.
INVALID_REQUEST_PARAM	Missing a required query parameter. Make sure you specified all required parameters. (e.g. reportType, requestId)
INVALID_REQUEST_PARAM	If the submission start date is beyond 30 days of the report expiration time, you will get an error.
INVALID_REQUEST_PARAM	Possibly missing start and end dates for Get All Reports API request. Try again with both dates provided.
INVALID_REQUEST_PARAM	Date specified might not be in correct date format.
MISSING_REQUEST_HEADER	The header is missing content. Make sure all required header parameters (e.g. channelType) are specified in the API call.
MISSING_REQUEST_PARAM	Make sure to specify the required request parameter (e.g reportType).
CONTENT_NOT_FOUND	The requestId could not be found. Try again with correct request ID.

Sellers can use the on-request Inventory report to view their entire inventory for all items across all fulfillment centers.

Once the report is available, sellers can download it to return all the information associated with the items that are set up on Walmart’s platform.

OPTIONAL: Use an app to parse the CSV file

Instead of downloading the CSV file, you can use an app to parse the CSV file for you, you can use the Java code shown in the Pre-generated Reports guide. See Parse reports CSV file with Java.

What’s in the Report file

The report shows individual rows for each fulfillment center that holds inventory for that item. For example, if you have one item at four fulfillment centers, you will see 4 rows in the report for that item, each row for the corresponding fulfillment center (aka “ship node”).

Here is an example to show the Report CSV file opened in a spreadsheet application.

Note: All example API calls shown assume the Walmart API endpoint: https://marketplace.walmartapis.com

Report Field Descriptions

The CSV report file contains the following fields. The identifiers can be specified by either the seller or Walmart.

Field	Description	Origin
SKU	Seller-specified unique identifier for the item.	Seller
Item ID	Walmart-specified identifier for the item.	Walmart
Product Name	Name of the item.	Seller
Ship Node ID	Identifies the Fulfillment Center (aka “Ship Node”)	Walmart
Ship Node Name	Name of the Fulfillment Center or “Ship Node.” This is a custom name that seller can create to identify the ship node, for example: “TwoDay_WestCoast” or “CA_Standard.”	Seller
Input Quantity	Quantity of an item that is input by the seller. This amount represents total item inventory including items that are sold but not yet shipped.	Seller
AvailToSell Quantity	Quantity of an item that is currently in-stock and available to sell. This inventory count does not show any items that are committed to open, undelivered orders.	Walmart

Step 1: Request the inventory report

To request an item report, call Create Report Request API.

For example, call v3/reports/reportRequests?reportType=INVENTORY&reportVersion=v1

Specify values for all required parameters:

• reportType – Specify which report you want to request (e.g. reportType=INVENTORY).
• reportVersion – Specify report version (e.g. reportVersion=v1).

Upon success, the API call returns a requestID, that you can use to find out if the report is ready for download, and status of the request (e.g. RECEIVED or INPROGRESS). It also returns values for requestSubmissionDate in UTC format: YYYY-MM-DDTHH:mm:ssZ.

You can also set up a Notification to trigger once the report status is READY. To set up a notification, see Notifications.

Step 2: Get report availability status

To find out if the report is ready for download, call Report Request Status API to retrieve report request status. When status is READY, you can download the report. The API can only retrieve details of requests created in the past 30 days.

For example, call v3/reports/reportRequests?{requestId} with the request ID.

Upon success, this call retrieves the status of the specified request ID (e.g. SUBMITTED, INPROGRESS, READY, or ERROR).

Step 3: (Optional) Subscribe to an event notification

To get a notification when the report you request is ready to download, create a Webhook notification. When the report status changes to READY, this triggers the notification.

For steps to subscribe, See Notifications. In addition to other required parameters, make sure to set resourceName to REPORTS, eventType to REPORT_STATUS, eventVersion to V1.

For example:

"resourceName": "REPORTS",
"eventType": "REPORT_STATUS",
"eventVersion": "V1",
"description": "Notification for report status"

Step 4: (Optional) Get a list of all requests

To get a list of all report requests in the last 30 days, call Get All Report Requests API. Request log does not continue to store requests past 30 days.

For example, call /v3/reports/reportRequests directly to retrieve a list of all requests.

(Optional): You can also filter the list with these query parameters:

• reportType – Specify a specific type of report only, for example reportType=INVENTORY for Inventory Report.
• requestId – Specify a single request ID to return.
• requestStatus – Request only report requests with one status to be returned: RECEIVED, INPROGRESS, READY, ERROR. For example requestStatus=READY.
• requestSubmissionStartDate – Specify a range of report requests and provide start date.
• requestSubmissionEndDate – Specify a range of report requests and provide end date.

Upon success, it retrieves a list of all reports that were requested with the Create Report Request API. It provides a list of request IDs by request submission date.

Example: Request all Reports that are Ready

If you want to return all current report requests that are currently ready, you can call:

/v3/reports/reportRequests?requestStatus=READY

Step 5: Download the report URL

To download a report you requested, call Download Report URL API and specify the requestID sent by the report status notification, or from a status API call.

For example, call /v3/reports/downloadReport?requestId={requestId}

Upon success, you receive the URL to download the report along with the URL expiration time:

• downloadURL – the URL to download the report.
• downloadURLExpirationTime – the download URL expiration time.

To avoid errors, make sure to check that these situations don’t apply to your request:

• The request has expired. In this case, the Report is no longer available.
• If the report is not available yet, check to see that status is not INPROGRESS.
• Could be either system error, or data errors.
• If the requestId is invalid. Make sure you have the correct ID, or that it hasn’t expired after 30 days.

Troubleshooting and Error Codes

If you get failures, here are some hints for how to solve these possible errors. Notice there are several reasons why you might get INVALID_REQUEST_PARAM error, depending on which API you call, and which parameters are required for that API.

Error Code	Description
SYSTEM_ERROR	There is an error in the system. Please wait and try again later.
INVALID_REQUEST_PARAM	Missing a required query parameter. Make sure you specified all required parameters. (e.g. reportType, requestId)
INVALID_REQUEST_PARAM	If the submission start date is beyond 30 days of the report expiration time, you will get an error.
INVALID_REQUEST_PARAM	Possibly missing start and end dates for Get All Reports API request. Try again with both dates provided.
INVALID_REQUEST_PARAM	Date specified might not be in correct date format.
MISSING_REQUEST_HEADER	The header is missing content. Make sure all required header parameters (e.g. channelType) are specified in the API call.
MISSING_REQUEST_PARAM	Make sure to specify the required request parameter (e.g reportType).
CONTENT_NOT_FOUND	The requestId could not be found. Try again with correct request ID.

Item has zero inventory count and N/A for ship node

If a row in the report holds the values for these four columns, it implies that the corresponding item was not updated since the ingestion:

• Ship Node ID = N/A
• Ship Node Name = N/A
• Input Quantity = 0
• AvailToSell Quantity = 0

To update item inventory, Call POST Update Item Inventory per Ship Node API. For more details about inventory updates, see Update item inventory.

The on-request Cancellation report provides details about cancelled orders.

Report Field Descriptions

The CSV report file contains the following fields. The identifiers can be specified by either the seller or Walmart.

Step 1: Request the cancellation report

To request an item report, call Create Report Request API.

For example, call v3/reports/reportRequests?reportType=CANCELLATION&reportVersion=v1

Specify values for all required parameters:

• reportType – Specify which report you want to request (e.g. reportType=CANCELLATION).
• reportVersion – Specify report version (e.g. reportVersion=v1).

Upon success, the API call returns a requestID, that you can use to find out if the report is ready for download, and status of the request (e.g. RECEIVED or INPROGRESS). It also returns values for requestSubmissionDate in UTC format: YYYY-MM-DDTHH:mm:ssZ.

You can also set up a Notification to trigger once the report status is READY. To set up a notification, see Notifications.

Step 2: Get report availability status

To find out if the report is ready for download, call Report Request Status API to retrieve report request status. When status is READY, you can download the report. The API can only retrieve details of requests created in the past 30 days.

For example, call v3/reports/reportRequests?{requestId} with the request ID.

Upon success, this call retrieves the status of the specified request ID (e.g. SUBMITTED, INPROGRESS, READY, or ERROR).

Step 3: (Optional) Subscribe to an event notification

To get a notification when the report you request is ready to download, create a Webhook notification. When the report status changes to READY, this triggers the notification.

For steps to subscribe, See Notifications. In addition to other required parameters, make sure to set resourceName to REPORTS, eventType to REPORT_STATUS, eventVersion to V1.

For example:

"resourceName": "REPORTS",
"eventType": "REPORT_STATUS",
"eventVersion": "V1",
"description": "Notification for report status"

Step 4: (Optional) Get a list of all requests

To get a list of all report requests in the last 30 days, call Get All Report Requests API. Request log does not continue to store requests past 30 days.

For example, call /v3/reports/reportRequests directly to retrieve a list of all requests.

(Optional): You can also filter the list with these query parameters:

• reportType – Specify a specific type of report only, for example reportType=CANCELLATION for cancellation Report.
• requestId – Specify a single request ID to return.
• requestStatus – Request only report requests with one status to be returned: RECEIVED, INPROGRESS, READY, ERROR. For example requestStatus=READY.
• requestSubmissionStartDate – Specify a range of report requests and provide start date.
• requestSubmissionEndDate – Specify a range of report requests and provide end date.

Upon success, it retrieves a list of all reports that were requested with the Create Report Request API. It provides a list of request IDs by request submission date.

Example: Request all Reports that are Ready

If you want to return all current report requests that are currently ready, you can call:

/v3/reports/reportRequests?requestStatus=READY

Step 5: Download the report URL

To download a report you requested, call Download Report URL API and specify the requestID sent by the report status notification, or from a status API call.

For example, call /v3/reports/downloadReport?requestId={requestId}

Upon success, you receive the URL to download the report along with the URL expiration time:

• downloadURL – the URL to download the report.
• downloadURLExpirationTime – the download URL expiration time.

To avoid errors, make sure to check that these situations don’t apply to your request:

• The request has expired. In this case, the Report is no longer available.
• If the report is not available yet, check to see that status is not INPROGRESS.
• Could be either system error, or data errors.
• If the requestId is invalid. Make sure you have the correct ID, or that it hasn’t expired after 30 days.

Troubleshooting and Error Codes

If you get failures, here are some hints for how to solve these possible errors. Notice there are several reasons why you might get INVALID_REQUEST_PARAM error, depending on which API you call, and which parameters are required for that API.

The on-request Delivery Defect report provides details about orders with on-time delivery issues.

Report Field Descriptions

The CSV report file contains the following fields. The identifiers can be specified by either the seller or Walmart.

Step 1: Request the delivery defect report

To request an item report, call Create Report Request API.

For example, call v3/reports/reportRequests?reportType=DELIVERY_DEFECT&reportVersion=v1

Specify values for all required parameters:

• reportType – Specify which report you want to request (e.g. reportType=DELIVERY_DEFECT).
• reportVersion – Specify report version (e.g. reportVersion=v1).

Upon success, the API call returns a requestID, that you can use to find out if the report is ready for download, and status of the request (e.g. RECEIVED or INPROGRESS). It also returns values for requestSubmissionDate in UTC format: YYYY-MM-DDTHH:mm:ssZ.

You can also set up a Notification to trigger once the report status is READY. To set up a notification, see Notifications.

Step 2: Get report availability status

To find out if the report is ready for download, call Report Request Status API to retrieve report request status. When status is READY, you can download the report. The API can only retrieve details of requests created in the past 30 days.

For example, call v3/reports/reportRequests?{requestId} with the request ID.

Upon success, this call retrieves the status of the specified request ID (e.g. SUBMITTED, INPROGRESS, READY, or ERROR).

Step 3: (Optional) Subscribe to an event notification

To get a notification when the report you request is ready to download, create a Webhook notification. When the report status changes to READY, this triggers the notification.

For steps to subscribe, See Notifications. In addition to other required parameters, make sure to set resourceName to REPORTS, eventType to REPORT_STATUS, eventVersion to V1.

For example:

"resourceName": "REPORTS",
"eventType": "REPORT_STATUS",
"eventVersion": "V1",
"description": "Notification for report status"

Step 4: (Optional) Get a list of all requests

To get a list of all report requests in the last 30 days, call Get All Report Requests API. Request log does not continue to store requests past 30 days.

For example, call /v3/reports/reportRequests directly to retrieve a list of all requests.

(Optional): You can also filter the list with these query parameters:

• reportType – Specify a specific type of report only, for example reportType=DELIVERY_DEFECT for delivery defect Report.
• requestId – Specify a single request ID to return.
• requestStatus – Request only report requests with one status to be returned: RECEIVED, INPROGRESS, READY, ERROR. For example requestStatus=READY.
• requestSubmissionStartDate – Specify a range of report requests and provide start date.
• requestSubmissionEndDate – Specify a range of report requests and provide end date.

Upon success, it retrieves a list of all reports that were requested with the Create Report Request API. It provides a list of request IDs by request submission date.

Example: Request all Reports that are Ready

If you want to return all current report requests that are currently ready, you can call:

/v3/reports/reportRequests?requestStatus=READY

Step 5: Download the report URL

To download a report you requested, call Download Report URL API and specify the requestID sent by the report status notification, or from a status API call.

For example, call /v3/reports/downloadReport?requestId={requestId}

Upon success, you receive the URL to download the report along with the URL expiration time:

• downloadURL – the URL to download the report.
• downloadURLExpirationTime – the download URL expiration time.

To avoid errors, make sure to check that these situations don’t apply to your request:

• The request has expired. In this case, the Report is no longer available.
• If the report is not available yet, check to see that status is not INPROGRESS.
• Could be either system error, or data errors.
• If the requestId is invalid. Make sure you have the correct ID, or that it hasn’t expired after 30 days.

Troubleshooting and Error Codes

If you get failures, here are some hints for how to solve these possible errors. Notice there are several reasons why you might get INVALID_REQUEST_PARAM error, depending on which API you call, and which parameters are required for that API.

The on-request Item Performance report provides insights into performance data of seller’s catalog.

Report Field Descriptions

The CSV report file contains the following fields. The identifiers can be specified by either the seller or Walmart.

Step 1: Request the item performance report

To request an item performance report, call Create Report Request API.

For example, call v3/reports/reportRequests?reportType=ITEM_PERFORMANCE&reportVersion=v1

Specify values for all required parameters:

• reportType – Specify which report you want to request (e.g. reportType=ITEM_PERFORMANCE).
• reportVersion – Specify report version (e.g. reportVersion=v1).

Upon success, the API call returns a requestID, that you can use to find out if the report is ready for download, and status of the request (e.g. RECEIVED or INPROGRESS). It also returns values for requestSubmissionDate in UTC format: YYYY-MM-DDTHH:mm:ssZ.

You can also set up a Notification to trigger once the report status is READY. To set up a notification, see Notifications.

Step 2: Get report availability status

To find out if the report is ready for download, call Report Request Status API to retrieve report request status. When status is READY, you can download the report. The API can only retrieve details of requests created in the past 30 days.

For example, call v3/reports/reportRequests?{requestId} with the request ID.

Upon success, this call retrieves the status of the specified request ID (e.g. SUBMITTED, INPROGRESS, READY, or ERROR).

Step 3: (Optional) Subscribe to an event notification

To get a notification when the report you request is ready to download, create a Webhook notification. When the report status changes to READY, this triggers the notification.

For steps to subscribe, See Notifications. In addition to other required parameters, make sure to set resourceName to REPORTS, eventType to REPORT_STATUS, eventVersion to V1.

For example:

"resourceName": "REPORTS",
"eventType": "REPORT_STATUS",
"eventVersion": "V1",
"description": "Notification for report status"

Step 4: (Optional) Get a list of all requests

To get a list of all report requests in the last 30 days, call Get All Report Requests API. Request log does not continue to store requests past 30 days.

For example, call /v3/reports/reportRequests directly to retrieve a list of all requests.

(Optional): You can also filter the list with these query parameters:

• reportType – Specify a specific type of report only, for example reportType=ITEM_PERFORMANCE for delivery defect Report.
• requestId – Specify a single request ID to return.
• requestStatus – Request only report requests with one status to be returned: RECEIVED, INPROGRESS, READY, ERROR. For example requestStatus=READY.
• requestSubmissionStartDate – Specify a range of report requests and provide start date.
• requestSubmissionEndDate – Specify a range of report requests and provide end date.

Upon success, it retrieves a list of all reports that were requested with the Create Report Request API. It provides a list of request IDs by request submission date.

Example: Request all Reports that are Ready

If you want to return all current report requests that are currently ready, you can call:

/v3/reports/reportRequests?requestStatus=READY

Step 5: Download the report URL

To download a report you requested, call Download Report URL API and specify the requestID sent by the report status notification, or from a status API call.

For example, call /v3/reports/downloadReport?requestId={requestId}

Upon success, you receive the URL to download the report along with the URL expiration time:

• downloadURL – the URL to download the report.
• downloadURLExpirationTime – the download URL expiration time.

To avoid errors, make sure to check that these situations don’t apply to your request:

• The request has expired. In this case, the Report is no longer available.
• If the report is not available yet, check to see that status is not INPROGRESS.
• Could be either system error, or data errors.
• If the requestId is invalid. Make sure you have the correct ID, or that it hasn’t expired after 30 days.

Troubleshooting and Error Codes

If you get failures, here are some hints for how to solve these possible errors. Notice there are several reasons why you might get INVALID_REQUEST_PARAM error, depending on which API you call, and which parameters are required for that API.

The on-request Return Overrides provides the sellers information of item level overrides for a SKU.

Filters are not yet supported, so when you generate the report you will receive all of the column data. However, you can filter the columns post-download with your CSV file.

Report Field Descriptions

The CSV report file contains the following fields. The identifiers can be specified by either the seller or Walmart.

Field	Description	Origin
SKU	Unique identifier for the item	Seller
Keep It	Allow customers to keep this item but still get a refund. Valid values are Yes, No, Blank.	Seller
Return Restricted	Item is restricted for return. Valid values are Yes, No, Blank.	Seller
Restriction Reason	Reason for restricting item for return.	Seller
Return Center (Alias)	Return Center (Alias) configured by seller	Seller
Publish Status	Whether or not the item is published on Walmart.com	Walmart

Step 1: Request the return item overrides report

Call Create Report Request API to request a return item overrides report.

For example, call: v3/reports/reportRequests?reportType=RETURN_OVERRIDES&reportVersion=v1

Specify values for all required parameters:

• reportType – Specify which report you want to request (e.g. reportType=RETURN_OVERRIDES).
• reportVersion – Specify report version (e.g. reportVersion=v1).

If successful, the API call returns a requestID, you can use to check if the report is ready to download the status request (e.g. RECEIVED or INPROGRESS). The call will provide values for requestSubmissionDate in UTC format: YYYY-MM-DDTHH:mm:ssZ.

You can set up a Notification to trigger when the report status is READY. See Notifications, to set up notifications.

Step 2: Get report availability status

Call Report Request Status API to retrieve report request status. You can download the report when the status is READY. The API can only retrieve details of requests created in the past 30 days.

For example, call: v3/reports/reportRequests?{requestId} with the request ID.

If successful, the call retrieves the status of the specified request ID (e.g. SUBMITTED, INPROGRESS, READY, or ERROR).

Step 3: (Optional) Subscribe to an event notification

You can create a Webhook notification for when the report you request is ready to download. The notification is triggered when the report status changes to READY.

See Notifications to create your Webhook notification. In addition to other required parameters, make sure to set resourceName to REPORTS, eventType to REPORT_STATUS, eventVersion to V1.

For example:

"resourceName": "REPORTS",
"eventType": "REPORT_STATUS",
"eventVersion": "V1",
"description": "Notification for report status"

Step 4: (Optional) Get a list of all requests

You can call Get All Report Requests API to request a list of all report requests in the last 30 days. Request log stores only 30 days of requests.

For example, call: /v3/reports/reportRequests directly to retrieve a list of all requests.

(Optional): You can also filter the list with these query parameters:

• reportType – Specify a specific type of report only, for example reportType=RETURN_OVERRIDES for return item overrides Report.
• requestId – Specify a single request ID to return.
• requestStatus – Request only report requests with one status to be returned: RECEIVED, INPROGRESS, READY, ERROR. For example requestStatus=READY.
• requestSubmissionStartDate – Specify a range of report requests and provide start date.
• requestSubmissionEndDate – Specify a range of report requests and provide end date.

If successful, it retrieves a list of all reports that were requested with the Create Report Request API. It provides a list of request IDs by request submission date.

Example: Request all Reports that are Ready

If you want to return all current report requests that are currently ready, you can call: /v3/reports/reportRequests?requestStatus=READY

Step 5: Download the report URL

Call the Download Report URL API to download the report by specifying the requestID sent by the report status notification, or from a status API call.

For example, call: /v3/reports/downloadReport?requestId={requestId}

Upon success, you receive the URL to download the report along with the URL expiration time:

• downloadURL – the URL to download the report.
• downloadURLExpirationTime – the download URL expiration time.

To avoid errors, make sure to check that these situations don’t apply to your request:

• The request has expired. In this case, the Report is no longer available.
• If the report is not available yet, check to see that status is not INPROGRESS.
• Could be either system error, or data errors.
• If the requestId is invalid. Make sure you have the correct ID, or that it hasn’t expired after 30 days.

Troubleshooting and Error Codes

If you get failures, here are some hints for how to solve these possible errors. Notice there are several reasons why you might get INVALID_REQUEST_PARAM error, depending on which API you call, and which parameters are required for that API.

Error Code	Description
SYSTEM_ERROR	There is an error in the system. Please wait and try again later.
INVALID_REQUEST_PARAM	Missing a required query parameter. Make sure you specified all required parameters. (e.g. reportType, requestId)
INVALID_REQUEST_PARAM	If the submission start date is beyond 30 days of the report expiration time, you will get an error.
INVALID_REQUEST_PARAM	Possibly missing start and end dates for Get All Reports API request. Try again with both dates provided.
INVALID_REQUEST_PARAM	Date specified might not be in correct date format.
MISSING_REQUEST_HEADER	The header is missing content. Make sure all required header parameters (e.g. channelType) are specified in the API call.
MISSING_REQUEST_PARAM	Make sure to specify the required request parameter (e.g reportType).
CONTENT_NOT_FOUND	The requestId could not be found. Try again with correct request ID.

Sellers can use the on-request Promotions report to view all active and future promotions that are set up with advance price information within a timeframe. The report provides information about Promotional prices including a start and end date for a promotional price to be active for an item, and other information.

You can use the Promotions Report API to process and download the zipped CSV file. The report contains only promotional prices with status: Activated, Deactivated, Updated or Created.

OPTIONAL: Use an app to parse the CSV file

Instead of downloading the CSV file, you can use an app to parse the CSV file for you, you can use the Java code shown in the Pre-generated Reports guide. See Parse reports CSV file with Java.

What’s in the Report file

The downloaded zip file provides the .csv file with the following information about your item promotions:

Field	Description	Origin
SKU	Unique ID of the product	Seller
Item ID	Numeric identifier that uniquely identifies the item	Walmart
Product Name	Name of the product	Seller
Product Category	Category of the product	Walmart
Promo ID	Unique ID of the promotion	Walmart
Promo Effective Date	The date the promotion begins	Seller
Promo Expiration Date	The date the promotion ends	Seller
Current Price	Promotion Price of the product	Seller
Current Price Currency	Currency of the promotion price of the product	Seller
Comparison Price	Base price of the product without promotion	Seller
Comparison Price Currency	Currency of the base price of the product	Seller
Promotion Type	Possible values are: Clearance, Reduced, Base	Seller
Promotion Status	Status of the promotion. Possible values are: Created, Updated, Activated, Deactivated.	Walmart

Step 1: Request the promotions report

Call the Create Report Request API to request the promotions report.

For example, call: v3/reports/reportRequests?reportType=PROMO&reportVersion=v1

Specify values for all required parameters:

• reportType – Specify which report you want to request (e.g. reportType=PROMO).
• reportVersion – Specify report version (e.g. reportVersion=v1).

Upon success, the API call returns a requestID, that you can use to find out if the report is ready for download, and status of the request (e.g. RECEIVED or INPROGRESS). It also returns values for requestSubmissionDate in UTC format: YYYY-MM-DDTHH:mm:ssZ.

You can also set up a Notification to trigger once the report status is READY. To set up a notification, see Notifications.

Step 2: Get report availability status

Call the Report Request Status API to retrieve report request status. When status is READY, you can download the report. The API can only retrieve details of requests created in the past 30 days.

For example, call: v3/reports/reportRequests?{requestId} with the request ID.

Upon success, this call retrieves the status of the specified request ID (e.g. SUBMITTED, INPROGRESS, READY, or ERROR).

Step 3: (Optional) Subscribe to an event notification

You can create a Webhook notification to recieve a notification when the requested report is ready to download. The notification is triggered when the report status changes to READY.

For steps to subscribe, See Notifications. In addition to other required parameters, make sure to set resourceName to REPORTS, eventType to REPORT_STATUS, eventVersion to V1.

For example:

"resourceName": "REPORTS",
"eventType": "REPORT_STATUS",
"eventVersion": "V1",
"description": "Notification for report status"

Step 4: (Optional) Get a list of all requests

You can call the Get All Report Requests API to get a list of all report requests in the last 30 days. The request log stores only 30 days of requests.

For example, call: /v3/reports/reportRequests directly to retrieve a list of all requests.

(Optional): You can also filter the list with these query parameters:

• reportType – Specify a specific type of report only, for example reportType=PROMO for Promotions Report.
• requestId – Specify a single request ID to return.
• requestStatus – Request only report requests with one status to be returned: RECEIVED, INPROGRESS, READY, ERROR. For example requestStatus=READY.
• requestSubmissionStartDate – Specify a range of report requests and provide start date.
• requestSubmissionEndDate – Specify a range of report requests and provide end date.

Upon success, it retrieves a list of all reports that were requested with the Create Report Request API. It provides a list of request IDs by request submission date.

Example: Request all Reports that are Ready

If you want to return all current report requests that are currently ready, you can call:

/v3/reports/reportRequests?requestStatus=READY

Step 5: Download the report URL

To download a report you requested, call Download Report URL API and specify the requestID sent by the report status notification, or from a status API call.

For example, call: /v3/reports/downloadReport?requestId={requestId}

Upon success, you receive the URL to download the report along with the URL expiration time:

• downloadURL – the URL to download the report.
• downloadURLExpirationTime – the download URL expiration time.

To avoid errors, make sure to check that these situations don’t apply to your request:

• The request has expired. In this case, the Report is no longer available.
• If the report is not available yet, check to see that status is not INPROGRESS.
• Could be either system error, or data errors.
• If the requestId is invalid. Make sure you have the correct ID, or that it hasn’t expired after 30 days.

Troubleshooting and Error Codes

If you get failures, here are some hints for how to solve these possible errors. Notice there are several reasons why you might get INVALID_REQUEST_PARAM error, depending on which API you call, and which parameters are required for that API.

Error Code	Description
SYSTEM_ERROR	There is an error in the system. Please wait and try again later.
INVALID_REQUEST_PARAM	Missing a required query parameter. Make sure you specified all required parameters. (e.g. reportType, requestId)
INVALID_REQUEST_PARAM	If the submission start date is beyond 30 days of the report expiration time, you will get an error.
INVALID_REQUEST_PARAM	Possibly missing start and end dates for Get All Reports API request. Try again with both dates provided.
INVALID_REQUEST_PARAM	Date specified might not be in correct date format.
MISSING_REQUEST_HEADER	The header is missing content. Make sure all required header parameters (e.g. channelType) are specified in the API call.
MISSING_REQUEST_PARAM	Make sure to specify the required request parameter (e.g reportType).
CONTENT_NOT_FOUND	The requestId could not be found. Try again with correct request ID.

The CPA report provides the Item Opt-in file with all SKUs that are eligible for a competitive price adjustment. If a SKU is not in this report, it is not eligible. If there are no SKUs and report is empty, then none of your items are eligible for price adjustment.

If the price displayed and charged to the customer is lower than the price submitted by the Seller for the item, the Seller receives the same payment for the item as if the item’s price was not adjusted.

For example, Seller sets the price of its eligible item at $50, with $5 shipping. The price displayed to the customer is $48 with $5 shipping, and the customer is charged $48, with $5 shipping. Seller receives payment for the sale as if the price charged and paid was $50 and $5 shipping.

OPTIONAL: Use an app to parse the CSV file

Instead of downloading the CSV file, you can use an app to parse the CSV file for you, you can use the Java code shown in the Pre-generated Reports guide. See Parse reports CSV file with Java.

Report Field Descriptions

The CSV report file contains the following fields. The identifiers can be specified by either the seller or Walmart.

Field	Description	Origin
SKU	An arbitrary alphanumeric unique ID, assigned by the Seller to each item in the XSD.	Seller
SKU OPT IN	The opt in status for the SKU	Seller
PRODUCT NAME	The product name on Walmart.com	Walmart
CURRENCY	The currency associated with price and shipment. (e.g., USD for US Dollars)	Seller
PRICE	The item’s current price	Seller
SHIP PRICE	The shipping price of the specified item	Seller

Step 1: Request the CPA report

Call the Create Report Request API to request the CPA report.

For example, call: v3/reports/reportRequests?reportType=CPA&reportVersion=v1

Specify values for all required parameters:

• reportType – Specify which report you want to request (e.g. reportType=CPA).
• reportVersion – Specify report version (e.g. reportVersion=v1).

Upon success, the API call returns a requestID, that you can use to find out if the report is ready for download, and status of the request (e.g. RECEIVED or INPROGRESS). It also returns values for requestSubmissionDate in UTC format: YYYY-MM-DDTHH:mm:ssZ.

You can also set up a Notification to trigger once the report status is READY. To set up a notification, see Notifications.

Step 2: Get report availability status

Call the Report Request Status API to retrieve report request status. When status is READY, you can download the report. The API can only retrieve details of requests created in the past 30 days.

For example, call: v3/reports/reportRequests?{requestId} with the request ID.

Upon success, this call retrieves the status of the specified request ID (e.g. SUBMITTED, INPROGRESS, READY, or ERROR).

Step 3: (Optional) Subscribe to an event notification

You can create a Webhook notification to recieve a notification when the requested report is ready to download. The notification is triggered when the report status changes to READY.

For steps to subscribe, See Notifications. In addition to other required parameters, make sure to set resourceName to REPORTS, eventType to REPORT_STATUS, eventVersion to V1.

For example:

"resourceName": "REPORTS",
"eventType": "REPORT_STATUS",
"eventVersion": "V1",
"description": "Notification for report status"

Step 4: (Optional) Get a list of all requests

You can call the Get All Report Requests API to get a list of all report requests in the last 30 days. The request log stores only 30 days of requests.

For example, call: /v3/reports/reportRequests directly to retrieve a list of all requests.

(Optional): You can also filter the list with these query parameters:

• reportType – Specify a specific type of report only, for example reportType=CPA for CPA Report.
• requestId – Specify a single request ID to return.
• requestStatus – Request only report requests with one status to be returned: RECEIVED, INPROGRESS, READY, ERROR. For example requestStatus=READY.
• requestSubmissionStartDate – Specify a range of report requests and provide start date.
• requestSubmissionEndDate – Specify a range of report requests and provide end date.

Upon success, it retrieves a list of all reports that were requested with the Create Report Request API. It provides a list of request IDs by request submission date.

Example: Request all Reports that are Ready

If you want to return all current report requests that are currently ready, you can call:

/v3/reports/reportRequests?requestStatus=READY

Step 5: Download the report URL

To download a report you requested, call Download Report URL API and specify the requestID sent by the report status notification, or from a status API call.

For example, call: /v3/reports/downloadReport?requestId={requestId}

Upon success, you receive the URL to download the report along with the URL expiration time:

• downloadURL – the URL to download the report.
• downloadURLExpirationTime – the download URL expiration time.

To avoid errors, make sure to check that these situations don’t apply to your request:

• The request has expired. In this case, the Report is no longer available.
• If the report is not available yet, check to see that status is not INPROGRESS.
• Could be either system error, or data errors.
• If the requestId is invalid. Make sure you have the correct ID, or that it hasn’t expired after 30 days.

Troubleshooting and Error Codes

If you get failures, here are some hints for how to solve these possible errors. Notice there are several reasons why you might get INVALID_REQUEST_PARAM error, depending on which API you call, and which parameters are required for that API.

Error Code	Description
SYSTEM_ERROR	There is an error in the system. Please wait and try again later.
INVALID_REQUEST_PARAM	Missing a required query parameter. Make sure you specified all required parameters. (e.g. reportType, requestId)
INVALID_REQUEST_PARAM	If the submission start date is beyond 30 days of the report expiration time, you will get an error.
INVALID_REQUEST_PARAM	Possibly missing start and end dates for Get All Reports API request. Try again with both dates provided.
INVALID_REQUEST_PARAM	Date specified might not be in correct date format.
MISSING_REQUEST_HEADER	The header is missing content. Make sure all required header parameters (e.g. channelType) are specified in the API call.
MISSING_REQUEST_PARAM	Make sure to specify the required request parameter (e.g reportType).
CONTENT_NOT_FOUND	The requestId could not be found. Try again with correct request ID.