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.
openapi: 3.0.1
info:
title: Walmart Notifications Management
description: Notifications Management API
servers:
- url: https://marketplace.walmartapis.com
description: Production URL
- url: https://sandbox.walmartapis.com
description: Sandbox URL
security:
- basicScheme: []
paths:
"/v3/webhooks/test":
post:
tags:
- Notifications
summary: Walmart Test Notification
description: This API can be used to send a test notification to the destination URL with the sample payload.
operationId: testNotification
parameters:
- in: header
name: WM_SEC.ACCESS_TOKEN
description: The access token retrieved in the Token API call
required: true
schema:
type: string
example: eyJraWQiOiIzZjVhYTFmNS1hYWE5LTQzM.....
- in: header
name: WM_CONSUMER.CHANNEL.TYPE
description: A unique ID to track the consumer request by channel. Use the Consumer Channel Type received during onboarding
required: false
schema:
type: string
- in: header
name: WM_QOS.CORRELATION_ID
description: A unique ID which identifies each API call and used to track and debug issues; use a random generated GUID for this ID
required: true
schema:
type: string
example: b3261d2d-028a-4ef7-8602-633c23200af6
- in: header
name: WM_SVC.NAME
description: Walmart Service Name
required: true
schema:
type: string
example: Walmart Service Name
requestBody:
description: Request fields
content:
application/json:
schema:
required:
- eventType
- eventUrl
- eventVersion
- resourceName
type: object
properties:
eventType:
type: string
description: Event that you want to subscribe to
eventVersion:
type: string
description: Version of the specific event type
resourceName:
type: string
description: Functional category that event type is mapped to.
eventUrl:
type: string
description: Destination URL where notification will be received by seller
authDetails:
type: object
properties:
authMethod:
type: string
description: 'enumeration: BASIC_AUTH,OAUTH,HMAC'
userName:
type: string
description: UserName to access destination URL
password:
type: string
description: Password to access destination URL
authHeaderName:
type: string
description: authHeaderName , using which authorization header will be passed
authUrl:
type: string
description: OAUTH URL
clientSecret:
type: string
description: Client Secret for OAUTH URL / HMAC
clientId:
type: string
description: ClientId for OAUTH URL
description: Authentication details for accessing the destination URL, if URL is protected
headers:
type: object
properties:
content-type:
type: string
description: Headers required for accessing the destination URL
examples:
sample:
value:
eventType: OFFER_UNPUBLISHED
eventVersion: V1
resourceName: ITEM
eventUrl: https://example.com/events
authDetails:
authMethod: BASIC_AUTH
userName: abc
password: test
authHeaderName: Authorization
headers:
content-type: application/json
required: true
responses:
'200':
description: Successful Operation
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: Message confirming that the eventURL is validated
example:
message: Eventurl successfully validated
"/v3/webhooks/subscriptions":
get:
tags:
- Notifications
summary: Walmart All Subscriptions
description: This API is used to retrieve the details of all subscriptions created using "create subscription" API.
operationId: getAllSubscriptions
parameters:
- name: subscriptionId
in: query
description: Use this to get details of a specific subscription
required: false
schema:
type: string
- name: eventType
in: query
description: Use this to get list of all subscriptions for a specific event type. Refer to Events section for list of available eventType.
required: false
schema:
type: string
- name: resourceName
in: query
description: Use this to get list of all subscriptions for a specific resource. Refer to Events section for list of available resourceName.
required: false
schema:
type: string
- name: status
in: query
description: Use this to get list of all subscriptions in ACTIVE or INACTIVE status
required: false
schema:
type: string
- in: header
name: WM_SEC.ACCESS_TOKEN
description: The access token retrieved in the Token API call
required: true
schema:
type: string
example: eyJraWQiOiIzZjVhYTFmNS1hYWE5LTQzM.....
- in: header
name: WM_CONSUMER.CHANNEL.TYPE
description: A unique ID to track the consumer request by channel. Use the Consumer Channel Type received during onboarding
required: false
schema:
type: string
- in: header
name: WM_QOS.CORRELATION_ID
description: A unique ID which identifies each API call and used to track and debug issues; use a random generated GUID for this ID
required: true
schema:
type: string
example: b3261d2d-028a-4ef7-8602-633c23200af6
- in: header
name: WM_SVC.NAME
description: Walmart Service Name
required: true
schema:
type: string
example: Walmart Service Name
responses:
'200':
description: Successful Operation
content:
application/json:
schema:
type: object
properties:
events:
type: array
description: List of events
items:
type: object
properties:
event:
type: array
items:
type: object
properties:
eventType:
type: string
description: Event for which the subscription is created
subscriptionId:
type: string
description: Unique ID for the subscription that can be used for fetching details, editing or deleting the subscription
partnerId:
type: string
description: Partner ID of the seller who created the subscription
eventVersion:
type: string
description: Version of the event type for which the subscription is created
resourceName:
type: string
description: Delegated access scope that event type is mapped to.
status:
type: string
description: ACTIVE or INACTIVE status of the subscription
eventUrl:
type: string
description: Destination URL where notification will be received by seller
authDetails:
type: object
properties:
authMethod:
type: string
description: 'enumeration: BASIC_AUTH,OAUTH,HMAC'
userName:
type: string
description: UserName to access destination URL
password:
type: string
description: Password to access destination URL
authHeaderName:
type: string
description: authHeaderName , using which authorization header will be passed
authUrl:
type: string
description: OAUTH URL
clientSecret:
type: string
description: Client Secret for OAUTH URL / HMAC
clientId:
type: string
description: ClientId for OAUTH URL
description: Authentication details for accessing the destination URL, if URL is protected
headers:
type: object
properties:
content-type:
type: string
description: Headers required for accessing the destination URL
description: List of events
examples:
sample1:
value:
events:
- eventType: OFFER_UNPUBLISHED
subscriptionId: 243ba4d0-b322-11ea-b385-0127e9b85538
partnerId: '10000000359'
eventVersion: V1
resourceName: ITEM
eventUrl: https://example.com/events
headers:
content-type: application/json
authDetails:
authHeaderName: Authorization
authMethod: BASIC_AUTH
userName: abc
password: test
status: INACTIVE
- eventType: PO_CREATED
subscriptionId: 343ba4d0-b322-11ea-b385-0127e9b85538
partnerId: '10000000359'
eventVersion: V1
resourceName: ORDER
eventUrl: https://example.com/orders
headers:
content-type: application/json
authDetails:
authHeaderName: Authorization
authMethod: BASIC_AUTH
userName: abc
password: test
status: ACTIVE
sample2:
value:
events:
- eventType: OFFER_UNPUBLISHED
subscriptionId: 243ba4d0-b322-11ea-b385-0127e9b85538
partnerId: '10000000359'
eventVersion: V1
resourceName: ITEM
eventUrl: https://example.com/events
headers:
content-type: application/json
authDetails:
authHeaderName: Authorization
authMethod: BASIC_AUTH
userName: abc
password: test
status: INACTIVE
- eventType: PO_CREATED
subscriptionId: 343ba4d0-b322-11ea-b385-0127e9b85538
partnerId: '10000000359'
eventVersion: V1
resourceName: ORDER
eventUrl: https://example.com/orders
headers:
content-type: application/json
authDetails:
authHeaderName: Authorization
authMethod: BASIC_AUTH
userName: abc
password: test
status: ACTIVE
- eventType: PO_LINE_AUTOCANCELLED
subscriptionId: 243ba4d0-b322-11ea-b385-0127e9b85538
partnerId: '10000000359'
eventVersion: V1
resourceName: ORDER
eventUrl: https://example.com/events
headers:
content-type: application/json
authDetails:
authHeaderName: Authorization
authMethod: BASIC_AUTH
userName: abc
password: test
status: ACTIVE
- eventType: BUY_BOX_CHANGED
subscriptionId: 243ba4d0-b322-11ea-b385-0127e9b85538
partnerId: '10000000359'
eventVersion: V1
resourceName: PRICE
eventUrl: https://example.com/events
headers:
content-type: application/json
authDetails:
authHeaderName: Authorization
authMethod: BASIC_AUTH
userName: abc
password: test
status: ACTIVE
post:
tags:
- Notifications
summary: Walmart Create Subscription
description: |-
This API is used to create subscription for notification of an event by selecting an event type, event version, resource name, and providing event URL. One or more than one events can be subscribed for notifications in one subscription request.
Use Get Event Types API to get the list of event type, event version and resource name available for subscribing.
Configure an event URL to receive the notifications.
URL Authentication Options
If authMethod is BASIC_AUTH, while making notification request to endpointUrl, Walmart system will pass authentication header with key as authHeaderName and value as BASE64 encoding of userName and password.
If authMethod is HMAC, while making notification request to endpointUrl, Walmart system will pass authentication header with key as authHeaderName and value as HMACSHA256 of complete response, using clientSecret as key.
If authMethod is OAUTH, Walmart system will make POST call to authUrl to generate token with request body as "grant_type=client_credentials" and headers as :
Authorization header with key as authHeaderName and value as BASE64 encoding of clientId and clientSecret
"Accept" :"application/json; charset=UTF-8"
"Content-type":"application/x-www-form-urlencoded; charset=ISO-8859-1"
Custom headers provided in headers field , if provided
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.
operationId: createSubscription
parameters:
- in: header
name: WM_SEC.ACCESS_TOKEN
description: The access token retrieved in the Token API call
required: true
schema:
type: string
example: eyJraWQiOiIzZjVhYTFmNS1hYWE5LTQzM.....
- in: header
name: WM_CONSUMER.CHANNEL.TYPE
description: A unique ID to track the consumer request by channel. Use the Consumer Channel Type received during onboarding
required: false
schema:
type: string
- in: header
name: WM_QOS.CORRELATION_ID
description: A unique ID which identifies each API call and used to track and debug issues; use a random generated GUID for this ID
required: true
schema:
type: string
example: b3261d2d-028a-4ef7-8602-633c23200af6
- in: header
name: WM_SVC.NAME
description: Walmart Service Name
required: true
schema:
type: string
example: Walmart Service Name
requestBody:
description: Request fields
content:
application/json:
schema:
type: object
properties:
events:
type: array
items:
required:
- eventType
- eventUrl
- eventVersion
- resourceName
- status
type: object
properties:
eventType:
type: string
description: Event that you want to subscribe to. For all allowed eventType(s) see Event Payload section or use GET Event Types API
eventVersion:
type: string
description: Version of the specific event type. For all eventVersion(s) for each eventType, see Event Payload section or use GET Event Types API
resourceName:
type: string
description: Delegated access scope that event type is mapped to. For all allowed resourceName(s) for each eventType, see Event Payload section or use GET Event Types API
eventUrl:
type: string
description: Destination URL where notification will be received by seller
authDetails:
type: object
properties:
authMethod:
type: string
description: 'enumeration: BASIC_AUTH,OAUTH,HMAC'
userName:
type: string
description: UserName to access destination URL
password:
type: string
description: Password to access destination URL
authHeaderName:
type: string
description: authHeaderName , using which authorization header will be passed
authUrl:
type: string
description: OAUTH URL
clientSecret:
type: string
description: Client Secret for OAUTH URL / HMAC
clientId:
type: string
description: ClientId for OAUTH URL
description: Authentication details for accessing the destination URL, if URL is protected
headers:
type: object
properties:
content-type:
type: string
description: Headers required for accessing the destination URL
status:
type: string
description: Status of the subscription. Allowed values are ACTIVE or INACTIVE. To create subscription, use status = ACTIVE. Notification will be triggered only if subscription is in ACTIVE status
examples:
sample1:
value:
events:
- eventType: OFFER_UNPUBLISHED
eventVersion: V1
resourceName: ITEM
eventUrl: https://example.com/events
status: ACTIVE
- eventType: PO_CREATED
eventVersion: V1
resourceName: ORDER
eventUrl: https://example.com/orders
status: ACTIVE
sample2:
value:
events:
- eventType: OFFER_UNPUBLISHED
eventVersion: V1
resourceName: ITEM
eventUrl: https://example.com/events
authDetails:
authMethod: BASIC_AUTH
userName: abc
password: test
authHeaderName: Authorization
headers:
content-type: application/json
status: ACTIVE
sample3:
value:
events:
- eventType: OFFER_UNPUBLISHED
eventVersion: V1
resourceName: ITEM
eventUrl: https://example.com/events
status: ACTIVE
- eventType: BUY_BOX_CHANGED
eventVersion: V1
resourceName: PRICE
eventUrl: https://example.com/orders
authDetails:
authMethod: BASIC_AUTH
userName: abc
password: test
authHeaderName: Authorization
headers:
content-type: application/json
status: ACTIVE
sample4:
value:
events:
- eventType: OFFER_UNPUBLISHED
eventVersion: V1
resourceName: ITEM
eventUrl: https://example.com/events
status: ACTIVE
- eventType: BUY_BOX_CHANGED
eventVersion: V1
resourceName: PRICE
eventUrl: https://example.com/orders
status: ACTIVE
- eventType: PO_CREATED
eventVersion: V1
resourceName: ORDER
eventUrl: https://example.com/events
status: ACTIVE
- eventType: PO_LINE_AUTOCANCELLED
eventVersion: V1
resourceName: ORDER
eventUrl: https://example.com/events
status: ACTIVE
required: true
responses:
'200':
description: Successful Operation
content:
application/json:
schema:
type: object
properties:
event:
type: array
items:
type: object
properties:
eventType:
type: string
description: Event for which the subscription is created
subscriptionId:
type: string
description: Unique ID for the subscription that can be used for fetching details, editing or deleting the subscription
partnerId:
type: string
description: Partner ID of the seller who created the subscription
eventVersion:
type: string
description: Version of the event type for which the subscription is created
resourceName:
type: string
description: Delegated access scope that event type is mapped to.
status:
type: string
description: ACTIVE or INACTIVE status of the subscription
eventUrl:
type: string
description: Destination URL where notification will be received by seller
authDetails:
type: object
properties:
authMethod:
type: string
description: 'enumeration: BASIC_AUTH,OAUTH,HMAC'
userName:
type: string
description: UserName to access destination URL
password:
type: string
description: Password to access destination URL
authHeaderName:
type: string
description: authHeaderName , using which authorization header will be passed
authUrl:
type: string
description: OAUTH URL
clientSecret:
type: string
description: Client Secret for OAUTH URL / HMAC
clientId:
type: string
description: ClientId for OAUTH URL
description: Authentication details for accessing the destination URL, if URL is protected
headers:
type: object
properties:
content-type:
type: string
description: Headers required for accessing the destination URL
description: List of events
example:
events:
- eventType: OFFER_UNPUBLISHED
subscriptionId: 620b45a0-b321-11ea-ac13-1f88d6025b7d
partnerId: '12300000359'
eventVersion: V1
resourceName: ITEM
status: ACTIVE
"/v3/webhooks/subscriptions/{subscriptionId}":
delete:
tags:
- Notifications
summary: Walmart Delete Subscription
description: This API is used to delete the subscription. Once deleted, the subscription cannot be retrieved.
operationId: deleteSubscription
parameters:
- name: subscriptionId
in: path
description: Unique ID for the subscription
required: true
schema:
type: string
- in: header
name: WM_SEC.ACCESS_TOKEN
description: The access token retrieved in the Token API call
required: true
schema:
type: string
example: eyJraWQiOiIzZjVhYTFmNS1hYWE5LTQzM.....
- in: header
name: WM_CONSUMER.CHANNEL.TYPE
description: A unique ID to track the consumer request by channel. Use the Consumer Channel Type received during onboarding
required: false
schema:
type: string
- in: header
name: WM_QOS.CORRELATION_ID
description: A unique ID which identifies each API call and used to track and debug issues; use a random generated GUID for this ID
required: true
schema:
type: string
example: b3261d2d-028a-4ef7-8602-633c23200af6
- in: header
name: WM_SVC.NAME
description: Walmart Service Name
required: true
schema:
type: string
example: Walmart Service Name
responses:
'200':
description: Successful Operation
content:
application/json:
schema:
type: object
properties:
subscriptionId:
type: string
description: Subscription Id of the subscription that is deleted
message:
type: string
description: Message confirming that the subscription has been deleted
example:
subscriptionId: subscriptionId
message: Successfully deleted subscription
patch:
tags:
- Notifications
summary: Walmart Update Subscription
description: This API is used to update the details of subscriptions. You can update event version, event URL, headers, authentication details of a subscription using this API. You can also disable/enable the subscription by changing the status from ACTIVE to INACTIVE or vice versa .
operationId: updateSubscription
parameters:
- name: subscriptionId
in: path
description: Unique ID for the subscription
required: true
schema:
type: string
- in: header
name: WM_SEC.ACCESS_TOKEN
description: The access token retrieved in the Token API call
required: true
schema:
type: string
example: eyJraWQiOiIzZjVhYTFmNS1hYWE5LTQzM.....
- in: header
name: WM_CONSUMER.CHANNEL.TYPE
description: A unique ID to track the consumer request by channel. Use the Consumer Channel Type received during onboarding
required: false
schema:
type: string
- in: header
name: WM_QOS.CORRELATION_ID
description: A unique ID which identifies each API call and used to track and debug issues; use a random generated GUID for this ID
required: true
schema:
type: string
example: b3261d2d-028a-4ef7-8602-633c23200af6
- in: header
name: WM_SVC.NAME
description: Walmart Service Name
required: true
schema:
type: string
example: Walmart Service Name
requestBody:
description: Request fields
content:
application/json:
schema:
type: object
properties:
eventType:
type: string
description: Event that is subscribed for notifications.
eventVersion:
type: string
description: Version of the specific event type
resourceName:
type: string
description: Delegated access scope that event type is mapped to.
eventUrl:
type: string
description: Destination URL where notification will be received by seller
authDetails:
type: object
properties:
authMethod:
type: string
description: 'enumeration: BASIC_AUTH,OAUTH,HMAC'
userName:
type: str
# --- truncated at 32 KB (61 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/walmart/refs/heads/main/openapi/walmart-marketplace-notifications-openapi-original.yml