Push notifications or Web Hooks trigger alerts to seller applications when specific events occur, such as an item is unpublished, a new purchase order is created, an item’s inventory is out of stock, etc. Whenever the trigger event occurs, Walmart will send a notification payload with event details to the seller-defined destination URL. Web Hooks help to optimize integration, automate workflows and reduce the number of times your application has to poll Walmart APIs within the throttle limits to determine if an event has occurred.
Notifications Workflow
The seller journey from subscription APIs and notifications follows this Workflow:
Subscribe to an event notification
You can subscribe to an event and get notified when that event occurs with Webhook notifications. To set up a subscription, you specify the event type, provide the app URL that you want to receive the notification, and set up all other notification preferences.
You can subscribe to more than one event per subscription request.
About Authentication Options
You have several options to authenticate with this API, however OAuth is recommended. To get more information about OAuth, see Authentication.
Authentication Method
authMethod
Usage
Basic
BASIC_AUTH
Authorization header uses userName and password encoded as BASE64.
HMAC
HMAC
Authorization header uses HMACSHA256 and clientSecret
OAuth
OAUTH
Authorization header uses clientIdandclientSecret and encoded in BASE64.
If there are custom headers provided in headers field, then authURL should return HTTPS status 200 and response should have access_token and expires_in field. While making notification request to endpointUrl, Walmart system will pass access_token in headers with authHeaderName as key and value as Bearer <access_token> along with any other custom headers provided in headers field.
About Resource Authorization
To subscribe to an event of a resource, make sure you have the delegated access scope for that resource. Each resource (e.g. Item or Feed) has permissions mapped based on Delegated Access.
If your delegated access scope for ITEM is view_only/ full_access, you can subscribe to all events of the Resource ‘ITEM’. If your delegated access scope for ITEM is no_access, you cannot subscribe to any events of the Resource ‘ITEM’.
However, you can fetch details of event types and subscriptions for all Resources irrespective of delegated access scopes.
Step 1: Test your destination URL
Before you create the subscription, you should validate the destination URL where you want to receive the notification. Make sure that your destination URL is a public http or https URL.
To test it out, call the Test Notification API and provide the required parameter values:
eventType – specify the name of the event (e.g. OFFER_UNPUBLISHED). For a complete list of available events, call Event Types API.
eventVersion – this depends on the event type. For details about each event time, select that event in Notifications. For example, Offer Unpublished Event takes eventVersion V1.
resourceName – provide the delegated scope that it can access, which is the functional category for the event type (e.g. Item).
eventURL – specify the destination URL to receive the event notification.
For a list of acceptable values for request parameters, see Create Subscription in the Reference.
You receive a success message to verify that the notification you set up with Create Subscriptions API will trigger for your event.
Once you verify the destination URL receives notifications with success, you can create a subscription. Call the Create Subscription API and specify all required parameters, similar to the call to Test Notification API.
If you want to get a list of all available events and resource names that you can subscribe to, use the Event Types API.
Specify values for authDetails parameters. For detailed descriptions of all request parameters, see Create Subscription API Reference.
Upon success, Walmart creates the subscription and provides you with the subscription ID.
Step 3: Set up notification acknowledgement
After Walmart sends the notification, your system needs to send acknowledgement with HTTP 2xx. You need to set up your system to respond to notifications with a standard HTTP status of 2xx.
If there is no 2xx status code acknowledgment, Walmart will retry three times to deliver the notification at intervals: 5 mins, 15 mins, 45 mins from the previous attempt.
(Optional) Step 4: Get a list of active notifications
To verify that your new notification is active, call All Subscriptions API. It will return all your current subscriptions.
Receive notifications for each event
After you create and test the subscription, Walmart will push the notifications to your destination URL whenever the event occurs.
Buy Box Changed Event
This event occurs when there is a change in Buy Box winner, or a buy box winning price on seller’s published items, if there is a minimum of 1 offer on the item.
When the event occurs, seller will receive the response payload, as given in the samples, on the destination URL.
Event Type: BUY_BOX_CHANGED
Event Version: V1
Resource Name: PRICE
Response Parameters
Name
Description
Type
source
Event Meta information
Object
eventType
Event for which the notification is received
String
eventTime
Time at which the event occurs
String
eventId
Unique Id of the event
String
payload
Event details
Object
partnerId
Seller’s Partner ID
String
itemInfo
Item information
Object
itemId
A unique Id which identifies the item
String
itemName
Name of the item
String
category
Category of the item
String
productType
Product type of the item
String
brand
Brand of the item
String
sku
A unique id which identifies the item
String
totalNumberOfOffers
No. of offers on the item from all sellers
Integer
offer
Offer information
Object
currentOffer
Seller’s current offer information
Object
sellerName
Seller’s name
String
sellerOfferPrice
Seller’s offer price on the item
Double
sellerShippingSpeed
Seller’s shipping speed on the item
String
sellerShippingPrice
Seller’s shipping price on the item
Double
winningOffer
Buy box winning offer information
Object
sellerName
Buy box winning seller’s name
String
sellerOfferPrice
Buy box winning seller’s offer price on the item
Double
sellerShippingSpeed
Buy box winning seller’s shipping speed on the item
String
sellerShippingPrice
Buy box winning seller’s shipping price on the item
Double
priceDifference
Difference of seller’s offer price with buy box winning offer price on the item
{
"source": {
"eventType": "OFFER_UNPUBLISHED",
"eventTime": "2019-02-21T01:01:08.000Z",
"eventId": "03d34580-61d4-11ea-9e23-cd38810ff7cd"
},
"payload": {
"partnerId": "12300014482",
"sku": "83852627",
"publishStatus": "UNPUBLISHED",
"lifecycleStatus": "ACTIVE",
"statusChangeReasons": {
"REASONABLE_PRICE_NOT_SATISFIED": "Reasonable price requirements are not met"
},
"itemId": "771087594",
"itemName": "OVE Decors Lynton 36 in. Fruit Single Sink Bathroom Vanity with Tiger Granite Top",
"category": "BATH AND LAUNDRY",
"totalNumberOfOffers": 7,
"sellerOfferPrice": 1049.95,
"sellerShippingPrice": 0,
"referencePrice": 680.59,
"referencePriceURL": "https://www.amazon.com/dp/B07NPLPTYH?psc=1",
"referencePriceType": "Amazon"
}
}
Purchase Order (PO) Created Event
This event occurs when there’s a new Purchase Order created for the seller.
When the purchase order event occurs, seller will receive the response payload, as given in the samples, on the destination URL.
Event Type: PO_CREATED
Event Version: V1
Resource Name: ORDER
Response Parameters
Name
Description
Type
source
Event Meta information
Object
eventType
Event for which the notification is received
String
eventTime
Time at which the event occurs
String
eventId
Unique Id of the event
String
payload
Event details
Object
partnerId
Seller’s Partner ID
String
purchaseOrderId
A unique ID associated with the seller’s purchase order
String
customerOrderId
A unique ID associated with the sales order for specified customer
String
orderDate
The date the customer submitted the sales order
String
estimatedDeliveryDate
The estimated time and date for the delivery of the item
String
estimatedShipDate
The estimated time and date when the item will be shipped
String
orderLines
Purchase Order line information for each item
List of OrderLine
lineNumber
The line number associated with the details for each individual item in the purchase order
String
sku
A unique id which identifies the item
String
productName
Name of the item
String
quantity
Details about the quantity
Object
unitOfMeasure
Unit of measurement
String
measurementValue
Quantity value
String
status
Status of the order line. Example: CREATED
String
statusDate
Date of most recent status shown on the order
String
shippingProgramType
Gives shipping program information. Examples: TWO_DAY, THREE_DAY, etc.
String
shippingMethod
Shipping Method. Examples: Value, Expedited, Standard, etc.
String
shipNodeType
Specifies the type of shipNode. Possible values are: SellerFulfilled, WFSFulfilled and 3PLFulfilled.
String
Sample Payload: Purchase Order Created
{
"source": {
"eventType": "PO_CREATED",
"eventTime": "2020-07-29T13:47:18.442Z",
"eventId": "04d868a0-d1a2-11ea-a710-459752d002e8"
},
"payload": {
"partnerId": "10000682332",
"purchaseOrderId": "2802123876439",
"customerOrderId": "4822046869501",
"orderDate": "2020-07-29T13:45:45.000Z",
"estimatedDeliveryDate": "2020-08-06T19:00:00.000Z",
"estimatedShipDate": "2020-07-31T03:00:00.000Z",
"orderLines": [
{
"lineNumber": "1",
"sku": "05S41A031",
"productName": "Girls Flip Flops 13-1 M US Little Kid Cute Mix N Match Print Slip On Summer Sandal F- Hello Summer",
"quantity": {
"unitOfMeasure": "EACH",
"measurementValue": "1"
},
"status": "Created",
"statusDate": "2020-07-29T13:47:18.216Z",
"shippingProgramType": "TWO_DAY",
"shippingMethod": "STANDARD"
},
{
"lineNumber": "2",
"sku": "05S41A003",
"productName": "Girls Flip Flops 13-1 M US Little Kid Cute Mix N Match Print Slip On Summer Thong Sandal E- Magical",
"quantity": {
"unitOfMeasure": "EACH",
"measurementValue": "1"
},
"status": "Created",
"statusDate": "2020-07-29T13:47:18.219Z",
"shippingProgramType": "TWO_DAY",
"shippingMethod": "STANDARD"
}
],
"shipNodeType": "SellerFulfilled"
}
}
Purchase Order (PO) Line Auto-cancelled Event
This notification occurs when a Purchase Order Line is auto-cancelled by Walmart if order is not updated to Shipped status with a valid tracking number by Estimated Ship Date (ESD) + 8 calendar days.
When the event occurs, seller will receive the response payload, as given in the samples, on the destination URL.
Event Type: PO_LINE_AUTOCANCELLED
Event Version: V1
Resource Name: ORDER
Response Parameters
Name
Description
Type
source
Event Meta information
Object
eventType
Event for which the notification is received
String
eventTime
Time at which the event occurs
String
eventId
Unique Id of the event
String
payload
Event details
Object
partnerId
Seller’s Partner ID
String
purchaseOrderId
A unique ID associated with the seller’s purchase order
String
customerOrderId
A unique ID associated with the sales order for specified customer
String
orderDate
The date the customer submitted the sales order
String
estimatedDeliveryDate
The estimated time and date for the delivery of the item
String
estimatedShipDate
The estimated time and date when the item will be shipped
String
orderLines
Purchase Order line information for each item
List of OrderLine
lineNumber
The line number associated with the details for each individual item in the purchase order
String
sku
A unique id which identifies the item
String
productName
Name of the item
String
quantity
Details about the quantity
Object
unitOfMeasure
Unit of measurement
String
measurementValue
Quantity value
String
status
Status of the order line. Example: CREATED
String
statusDate
Date of most recent status shown on the order
String
shippingProgramType
Gives shipping program information. Examples: TWO_DAY, THREE_DAY, etc.
String
shippingMethod
Shipping Method. Examples: Value, Expedited, Standard, etc.
String
cancellationReason
Reason for cancellation of PO Line
String
shipNodeType
Specifies the type of shipNode. Possible values are: SellerFulfilled, WFSFulfilled and 3PLFulfilled.
Report status notification is triggered when the report requested by seller with the Create Report Request API moves to READY status and is available to download.
When the report status notification event occurs, seller will receive the response payload, as given in the samples, on the destination URL.
{"source":{"eventType":"REPORT_STATUS","eventTime":"2020-07-03T14:12:42.913Z","eventId":"e435c380-fbe6-11ea-bc39-c314c32822dc"},"payload":{"partnerId":"10902014482","requestId":"6da7357b-1c3b-4c1d-9685-ca2931eb96b4","requestStatus":"ERROR","requestSubmissionDate": "2020-12-10T07:08:35.393Z","reportGenerationDate": "2020-12-10T07:21:34.473Z","reportType":"ITEM","reportVersion":"v1","errorDescription":"Your report request has resulted in error. Please try creating a new request."}}
