Notifications

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.

The seller journey from subscription APIs and notifications follows this Workflow:

This API provides the list of event types and resource names that you can subscribe to. Notifications will be triggered only for the event types that you subscribe to.

Event Types are workflow events that are triggered when status or conditions change. Some examples are an offer moving from published to unpublished status, an order getting auto-canceled by Walmart, a buy box price/winner change, etc.

Resource Names are functional API categories that group similar event types. Resource Names can be Item, Price, Order, Inventory, etc. The permissions to subscribe to an Event Type are defined by Resource Name which is mapped to permissions in Delegated Access.

API Specifications

• API Version: V3
• URL For Production
  REST – GET: https://marketplace.walmartapis.com/v3/webhooks/eventTypes
• URL Sample
  GET /v3/webhooks/eventTypes HTTP/1.1

Sample Header

<<Authentication Headers>>

Content-Type: application/json

Accept: application/json

Host: marketplace.walmartapis.com

Header parameter Description

For authentication headers, please refer to the Authentication section.

"data": [

{
"Name": "Content-type",
"Description": "The data format in the API payload",
"Required": "No",
"Example": "application/json"
},
{
"Name": "Accept",
"Description": "The returned data format in the response",
"Required": "Yes",
"Example": "application/json"
}

]

Sample Requests

{
"resourceName": "ITEM",
"eventType": "OFFER_PUBLISHED",
"eventVersion": "V1",
"description": "Notification for published offers"
}

Request parameter Description

Sample Response 1

{

"events": [
{
"resourceName": "ITEM",
"eventType": "OFFER_UNPUBLISHED",
"eventVersion": "V1",
"description": "Notification for unpublished offers"
},

{
"resourceName": "PRICE",
"eventType": "BUY_BOX_CHANGED",
"eventVersion": "V1",
"description": "Notification for change in buy box"
},

{
"resourceName": "ORDER",
"eventType": "PO_CREATED",
"eventVersion": "V1",
"description": "Notification for new purchase order created"
},

{
"resourceName": "ORDER",
"eventType": "PO_LINE_AUTOCANCELLED",
"eventVersion": "V1",
"description": "Notification for purchase order line auto-cancelled"
},

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

{
"resourceName": "INVENTORY",
"eventType": "INVENTORY_OOS",
"eventVersion": "V1",
"description": "Notification for inventory out of stock"
},



{
 "resourceName": "ITEM",
 "eventType": "OFFER_PUBLISHED",
 "eventVersion": "V1",
 "description": "Notification for published offers"
 }


]
}

Sample Response 2

"data": [

{
"Name": "events",
"Description": "List of events",

"Type": "Array"
},

{
"Name": "eventType",
"Description": "Event that you want to subscribe to.",
"Type": "String"
},
{
"Name": "eventVersion",
"Description": "Version of the specific event type",
"Type": "String"
},
{
"Name": "resourceName",
"Description": "Delegated access scope that event type is mapped to.",
"Type": "String"
},
{
"Name": "description",
"Description": "Description of the specific event type",
"Type": "String"
}

]

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.

Example request

For a sample request, see Test Notification API Reference.

Step 2: Create a subscription

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.

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	Double

Sample Payload: Buy Box Changed

{
  "source": {
    "eventType": "BUY_BOX_CHANGED",
    "eventTime": "2020-07-03T14:12:42.913Z",
    "eventId": "42c2b910-bd37-11ea-89f1-4f3bd9e0e3af"
  },
  "payload": {
    "partnerId": "12300001205",
    "itemInfo": {
      "itemId": "50655131",
      "itemName": "Sizzix SBarnard Thinlits Die Drop In Thank You",
      "category": "Crafts",
      "productType": "Die-Cut Cartridges",
      "brand": "Sizzix",
      "sku": "NMG300868",
      "totalNumberOfOffers": 33
    },
    "offer": {
      "currentOffer": {
        "sellerName": "CB&WS goods",
        "sellerOfferPrice": 13.03,
        "sellerShippingSpeed": "STANDARD",
        "sellerShippingPrice": 8.99
      },
      "winningOffer": {
        "sellerName": "Save you Stores",
        "sellerOfferPrice": 16.25,
        "sellerShippingSpeed": "EXPEDITED",
        "sellerShippingPrice": 0
      },
      "priceDifference": -3.22
    }
  }
}

When the inventory oos notification event occurs, the seller will receive the response payload, as given in the sample, at the destination URL.

This notification is triggered when an inventory is out of stock.

• Event Type: INVENTORY_OOS
• Event Version: V1
• Resource Name: INVENTORY

Response Parameters

Sample Payload 1: Inventory OOS

{
    "source": {
        "eventType": "INVENTORY_OOS",
        "eventTime": "2021-03-31T06:39:54.726Z",
        "eventId": "e734a060-91eb-11eb-8024-dbd12dd659ed"
    },
    "payload": {
        "partnerId": "123633591",
        "itemId": "286687472",
        "sku": "PORA-L500-Light-Stone-L",
        "productName": "Port Authority Women's Polo",
        "category": "Clothing, Shoes & Accessories",
        "shipNodes": [
            {
                "availToSellQty": 0,
                "shipNode": "633591",
                "shipNodeName": "633591@PORA-L500-Light-Stone-L@ACTIVE"
            }
        ]
    }
}

This notification is triggered when an offer is published.

When the offer published event occurs, the seller receives the response payload shown below at the destination URL.

• Event Type: OFFER_PUBLISHED
• Event Version: V1
• Resource Name: ITEM

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
itemId	A unique Id that identifies the item	String
sku	A unique Id that identifies the item	String
publishStatus	The offer publish status	String
lifecycleStatus	The offer lifecycle status	String
itemName	The item name	String
category	The item category	String
totalNumberOfOffers	The total number of offers	Integer
sellerOfferPrice	The Seller Offer price	Double
sellerShippingPrice	The Seller Shipping price	Double

Sample Payload 1: Offer Published

{
    "source": {
        "eventType": "OFFER_PUBLISHED",
        "eventTime": "2021-01-21T01:09:08.000Z",
        "eventId": "04d34580-61d4-11ea-9e23-cd38810ff7cw"
    },
    "payload": {
        "partnerId": "10900014482",
        "sku": "83852627",
        "publishStatus": "PUBLISHED",
        "lifecycleStatus": "ACTIVE",
        "itemId": "771087594",
        "itemName":"OVE Decors Lynton 39 in. Fruit Single Sink Bathroom Vanity with Tiger Granite Top",
        "category": "BATH AND LAUNDRY",
        "totalNumberOfOffers": 28,
        "sellerOfferPrice": 1100.72,
        "sellerShippingPrice": 0.0
    }
}

Offer Unpublished Event is when seller’s offer moves from Published status to Unpublished status.

When the event occurs, seller will receive the response payload, as given in the samples, on the destination URL.

• Event Type: OFFER_UNPUBLISHED
• Event Version: V1
• Resource Name: ITEM

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
sku	A unique Id which identifies the item	String
publishStatus	Status of the item in the submission process	String
lifecycleStatus	Status of the item in the overall lifecycle	String
statusChangeReasons	Reason for the item to be unpublished. If there are multiple reasons for the item to be unpublished, all will be listed here.	Map<String,String>
itemId	A unique Id which identifies the item. Received only if statusChangeReasons = REASONABLE_PRICE_NOT_SATISFIED	String
itemName	Name of the item. Received only if statusChangeReasons = REASONABLE_PRICE_NOT_SATISFIED	String
category	Category of the item. Received only if statusChangeReasons = REASONABLE_PRICE_NOT_SATISFIED	String
totalNumberOfOffers	No. of offers on the item from all sellers. Received only if statusChangeReasons = REASONABLE_PRICE_NOT_SATISFIED	Integer
sellerOfferPrice	Seller’s offer price on the item. Received only if statusChangeReasons = REASONABLE_PRICE_NOT_SATISFIED	Double
sellerShippingPrice	Seller’s shipping price on the item. Received only if statusChangeReasons = REASONABLE_PRICE_NOT_SATISFIED	Double
referencePrice	Reference price used for offer to be unpublished. Received only if statusChangeReasons = REASONABLE_PRICE_NOT_SATISFIED	Double
referencePriceURL	URL for the reference price. Received only if statusChangeReasons = REASONABLE_PRICE_NOT_SATISFIED	String
referencePriceType	Source of the reference price. Received only if statusChangeReasons = REASONABLE_PRICE_NOT_SATISFIED	String

Sample Payload 1: Offer Unpublished

{
  "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": {
      "SHIPPING_INFO_MISSING": "No shipping information was set up."
    }
  }
}

Sample Payload 2: Offer Unpublished

{
  "source": {
    "eventType": "OFFER_UNPUBLISHED",
    "eventTime": "2019-02-21T01:01:08.000Z",
    "eventId": "03d34580-61d4-11ea-9e23-cd38810ff7cd"
  },
  "payload": {
    "partnerId": "12300014482",
    "sku": "9458276",
    "publishStatus": "UNPUBLISHED",
    "lifecycleStatus": "ACTIVE",
    "statusChangeReasons": {
      "REASONABLE_PRICE_NOT_SATISFIED": "Reasonable price requirements are not met"
    },
    "itemId": "21125774",
    "itemName": "Pantene Pro-V Daily Moisture Renewal Shampoo, 12.6 fl oz",
    "category": "HAIR CARE",
    "totalNumberOfOffers": 28,
    "sellerOfferPrice": 11.72,
    "sellerShippingPrice": 0,
    "referencePrice": 9.47
  }
}

Sample Payload 3: Offer Unpublished

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

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"
  }
}

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

Sample Payload: PO Line Auto-cancelled

{
    "source": {
      "eventType": "PO_LINE_AUTOCANCELLED",
      "eventTime": "2020-07-03T14:12:42.913Z",
      "eventId": "42c2b910-bd37-11ea-89f1-4f3bd9e0e3af"
    },
    "payload": {
      "partnerId": "10000680931",
      "purchaseOrderId": "1805600225946",
      "customerOrderId": "1594199846496",
      "orderDate": "2020-07-05T01:05:09+00:00",
      "estimatedDeliveryDate": "2020-07-17T19:00:00+00:00",
      "estimatedShipDate": "2020-07-09T03:00:00+00:00",
      "orderLines": [
        {
          "lineNumber": "1",
          "sku": "9133KHAKIL",
          "productName": "Healing Hands Purple Label Women's Tori 5-Pocket Scrub Pant",
          "quantity": {
            "unitOfMeasure": "EACH",
            "measurementValue": "1"
          },
          "status": "Cancelled",
          "statusDate": "2020-07-17T03:19:55.752+00:00",
          "shippingProgramType": "TWO_DAY",
          "shippingMethod": "VALUE",
          "cancellationReason": "Auto-cancelled due to expiry"
        }
      ],
      "shipNodeType": "SellerFulfilled"
    }
  }

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.

• Event Type: REPORT_STATUS
• Event Version : V1
• Resource Name: REPORTS

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
requestId	Unique ID for the Report generation request	String
requestStatus	Status of the Report generation request	String
requestSubmissionDate	Request submission time	String
reportGenerationDate	Report generation time	String
reportType	Type of Report	String
reportVersion	Version of Report	String
errorDescription	Error description, in case of an error	String

Sample Payload 1: Report Status Event

{
"source": {
"eventType": "REPORT_STATUS",
"eventTime": "2020-07-03T14:12:42.913Z",
"eventId": "03d34580-61d4-11ea-9e23-cd38810ff7cd"
},
"payload": {
"partnerId": "10902014482",
"requestId": "6da7357b-1c3b-4c1d-9685-ca2931eb96b4",
"requestStatus": "READY",
"requestSubmissionDate":  "2020-12-10T07:08:35.393Z",
"reportGenerationDate": "2020-12-10T07:21:34.473Z",
"reportType": "ITEM",
"reportVersion": "v1"
}
}

Sample Payload 2: Report Status Event

{
"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."
}
}