Walmart Promotions API
Sellers can set regular or promotional prices for their items. Setting the Promotional prices is an option to create unique pricing for events such as clearance sales or to call out a comparison price.
OpenAPI Specification
openapi: 3.0.1
info:
title: Walmart Promotion Management
description: Sellers can set regular or promotional prices for their items. Setting the Promotional prices is an option to create unique pricing for events such as clearance sales or to call out a comparison price
servers:
- url: https://marketplace.walmartapis.com
description: Production URL
- url: https://sandbox.walmartapis.com
description: Sandbox URL
security:
- basicScheme: []
paths:
"/v3/price":
put:
tags:
- Promotions
summary: Walmart Update a Promotional Price
description: |-
Updates the promotional price.
Sellers can update or delete an existing promotional price as well as set up a new promotional price.
To set a new promotional price or update an existing one, set the XML pricing attribute processMode to UPSERT.
To delete a promotional price, set the XML pricing attribute processMode to DELETE.
To delete all promotions for a SKU, set replaceAll to an empty payload.
operationId: updatePromotionalPrices
parameters:
- name: promo
in: query
description: The promotional price. Set to 'true' in order to retrieve promotional prices
required: true
schema:
type: boolean
default: true
- 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: The request body consists of a Feed file attached to the request.
content:
application/json:
schema:
required:
- pricing
- sku
type: object
properties:
offerId:
type: string
description: This is applicable only for promotions
sku:
type: string
replaceAll:
type: string
description: This is applicable only for promotions
enum:
- 'true'
- 'false'
pricing:
type: array
items:
required:
- currentPrice
- currentPriceType
type: object
properties:
effectiveDate:
type: string
description: This is applicable only for promotions
format: date-time
expirationDate:
type: string
description: This is applicable only for promotions
format: date-time
promoId:
type: string
description: This is applicable only for promotions
processMode:
type: string
description: This is applicable only for promotions
enum:
- UPSERT
- DELETE
currentPriceType:
type: string
description: This is applicable only for both promotions and price
enum:
- BASE
- REDUCED
- CLEARANCE
currentPrice:
type: object
properties:
currency:
type: string
enum:
- USD
- CAD
amount:
type: number
format: double
comparisonPriceType:
type: string
description: This is applicable only for promotions
enum:
- BASE
comparisonPrice:
type: object
properties:
currency:
type: string
enum:
- USD
- CAD
amount:
type: number
format: double
description: This is applicable only for promotions
priceDisplayCodes:
type: string
description: Represent promo placement. This is applicable only for promotions
enum:
- CART
- CHECKOUT
definitions:
type: object
examples:
Promotional Pricing Update JSON:
value:
sku: 97964_KFTest
pricing:
- currentPrice:
currency: USD
amount: 4
currentPriceType: REDUCED
comparisonPriceType: BASE
comparisonPrice:
currency: USD
amount: 4
priceDisplayCodes: CART
effectiveDate: '2019-11-03T09:49:57.943Z'
expirationDate: '2019-12-03T09:49:57.943Z'
processMode: UPSERT
required: true
responses:
'200':
description: Successful Operation
content:
application/json:
schema:
type: object
properties:
errors:
type: array
xml:
name: error
items:
required:
- code
type: object
properties:
code:
type: string
field:
type: string
description:
type: string
info:
type: string
severity:
type: string
enum:
- INFO
- WARN
- ERROR
category:
type: string
enum:
- APPLICATION
- SYSTEM
- REQUEST
- DATA
causes:
type: array
xml:
wrapped: true
items:
type: object
properties:
code:
type: string
field:
type: string
type:
type: string
description:
type: string
xml:
name: Cause
errorIdentifiers:
type: object
additionalProperties:
type: object
component:
type: string
type:
type: string
serviceName:
type: string
gatewayErrorCategory:
type: string
enum:
- INTERNAL_DATA_ERROR
- EXTERNAL_DATA_ERROR
- SYSTEM_ERROR
xml:
name: GatewayError
statusCode:
type: integer
format: int32
mart:
type: string
description: 'Marketplace name. Example: Walmart-US'
xml:
namespace: http://walmart.com/
sku:
type: string
description: An arbitrary alphanumeric unique ID, specified by the seller, which identifies each item.
xml:
namespace: http://walmart.com/
message:
type: string
description: A message of acknowledgement for a price update
xml:
namespace: http://walmart.com/
xml:
name: ItemPriceResponse
namespace: http://walmart.com/
example:
ItemPriceResponse:
mart: WALMART_US
message: Thank you. Your price has been updated. Please allow up to five minutes for this change to be reflected on the site.
sku: 97964_KFTest
application/xml:
schema:
type: object
properties:
errors:
type: array
xml:
name: error
items:
required:
- code
type: object
properties:
code:
type: string
field:
type: string
description:
type: string
info:
type: string
severity:
type: string
enum:
- INFO
- WARN
- ERROR
category:
type: string
enum:
- APPLICATION
- SYSTEM
- REQUEST
- DATA
causes:
type: array
xml:
wrapped: true
items:
type: object
properties:
code:
type: string
field:
type: string
type:
type: string
description:
type: string
xml:
name: Cause
errorIdentifiers:
type: object
additionalProperties:
type: object
component:
type: string
type:
type: string
serviceName:
type: string
gatewayErrorCategory:
type: string
enum:
- INTERNAL_DATA_ERROR
- EXTERNAL_DATA_ERROR
- SYSTEM_ERROR
xml:
name: GatewayError
statusCode:
type: integer
format: int32
mart:
type: string
description: 'Marketplace name. Example: Walmart-US'
xml:
namespace: http://walmart.com/
sku:
type: string
description: An arbitrary alphanumeric unique ID, specified by the seller, which identifies each item.
xml:
namespace: http://walmart.com/
message:
type: string
description: A message of acknowledgement for a price update
xml:
namespace: http://walmart.com/
xml:
name: ItemPriceResponse
namespace: http://walmart.com/
example: |
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:ItemPriceResponse xmlns:ns2="http://walmart.com/">
<ns2:mart>WALMART_US</ns2:mart>
<ns2:sku>97964_KFTest</ns2:sku>
<ns2:message>Thank you. Your price has been updated. Please allow up to five minutes for this change to be reflected on the site.</ns2:message>
</ns2:ItemPriceResponse>
"/v3/feeds":
post:
tags:
- Promotions
summary: Walmart Updates Bulk Promotional Prices
description: Updates or creates promotional prices for multiple specified SKUs
operationId: updateBulkPromotionalPrice
parameters:
- name: feedType
in: query
description: Feed Type
required: true
schema:
type: string
default: promo
- 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: 'The request body consists of a Feed file attached to the request. '
content:
multipart/form-data:
schema:
required:
- file
type: object
properties:
file:
type: string
description: Feed file to upload
format: binary
required: true
responses:
'200':
description: Successful Operation
content:
application/json:
schema:
type: object
properties:
feedId:
type: string
description: A unique ID, returned from the Bulk Upload API, used for tracking the Feed File.
example:
feedId: 609B1E4C0B3E48989690263DEAC85C63@AVUBAQA
application/xml:
schema:
type: object
properties:
feedId:
type: string
description: A unique ID, returned from the Bulk Upload API, used for tracking the Feed File.
example: |-
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:FeedAcknowledgement xmlns:ns2="http://walmart.com/">
<ns2:feedId>55DE8A53B09F41BBBF261C1AB5FB2BC8@AVMBAgA</ns2:feedId>
</ns2:FeedAcknowledgement>
"/v3/promo/sku/{sku}":
get:
tags:
- Promotions
summary: Walmart Promotional Prices
description: " Retrieves a list of promotional prices for a single SKU."
operationId: getPromotionalPrices
parameters:
- name: sku
in: path
description: 'An arbitrary alphanumeric unique ID, specified by the seller, which identifies each item. This will be used by the seller in the XSD file to refer to each item. Special characters in the sku needing encoding are: '':'', ''/'', ''?'', ''#'', ''['', '']'', ''@'', ''!'', ''$'', ''&'', "''", ''('', '')'', ''*'', ''+'', '','', '';'', ''='', as well as ''%'' itself. Other characters don''t need to be encoded.'
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:
payload:
required:
- itemIdentifier
- pricingList
type: object
properties:
itemIdentifier:
type: object
properties:
sku:
type: string
offerId:
type: string
itemId:
type: string
wpid:
type: string
productType:
type: string
pricingList:
required:
- pricing
type: object
properties:
replaceAll:
type: boolean
xml:
attribute: true
pricing:
type: array
items:
required:
- currentPrice
- currentPriceType
type: object
properties:
currentPrice:
type: object
properties:
value:
type: object
properties:
value:
type: string
currency:
type: string
xml:
attribute: true
amount:
type: number
xml:
attribute: true
uomType:
type: string
minValue:
type: object
properties:
value:
type: string
currency:
type: string
xml:
attribute: true
amount:
type: number
xml:
attribute: true
maxValue:
type: object
properties:
value:
type: string
currency:
type: string
xml:
attribute: true
amount:
type: number
xml:
attribute: true
perUnitValue:
type: object
properties:
value:
type: string
currency:
type: string
xml:
attribute: true
amount:
type: number
xml:
attribute: true
minUnitValue:
type: object
properties:
value:
type: string
currency:
type: string
xml:
attribute: true
amount:
type: number
xml:
attribute: true
maxUnitValue:
type: object
properties:
value:
type: string
currency:
type: string
xml:
attribute: true
amount:
type: number
xml:
attribute: true
currentPriceType:
type: string
enum:
- BASE
- REDUCED
- SAVINGS_AMT
- SAVINGS_PCT
- ROLLBACK
- CLEARANCE
- LIST_PRICE
comparisonPrice:
type: object
properties:
value:
type: object
properties:
value:
type: string
currency:
type: string
xml:
attribute: true
amount:
type: number
xml:
attribute: true
uomType:
type: string
minValue:
type: object
properties:
value:
type: string
currency:
type: string
xml:
attribute: true
amount:
type: number
xml:
attribute: true
maxValue:
type: object
properties:
value:
type: string
currency:
type: string
xml:
attribute: true
amount:
type: number
xml:
attribute: true
perUnitValue:
type: object
properties:
value:
type: string
currency:
type: string
xml:
attribute: true
amount:
type: number
xml:
attribute: true
minUnitValue:
type: object
properties:
value:
type: string
currency:
type: string
xml:
attribute: true
amount:
type: number
xml:
attribute: true
maxUnitValue:
type: object
properties:
value:
type: string
currency:
type: string
xml:
attribute: true
amount:
type: number
xml:
attribute: true
comparisonPriceType:
type: string
enum:
- BASE
- REDUCED
- SAVINGS_AMT
- SAVINGS_PCT
- ROLLBACK
- CLEARANCE
- LIST_PRICE
savingsAmount:
type: number
savingsPercent:
type: number
priceDisplayCodes:
type: object
properties:
isClearance:
type: boolean
hidePriceForSOI:
type: object
submapType:
type: object
isRollback:
type: boolean
isReducedPrice:
type: boolean
isEligibleForAssociateDiscount:
type: object
isStrikethrough:
type: boolean
pickupDiscount:
type: object
properties:
isPickUpDiscountEligible:
type: boolean
xml:
attribute: true
pickupDiscountAmt:
type: object
properties:
value:
type: string
currency:
type: string
xml:
attribute: true
amount:
type: number
xml:
attribute: true
effectiveDate:
type: integer
format: int64
xml:
attribute: true
expirationDate:
type: integer
format: int64
xml:
attribute: true
processMode:
type: string
# --- truncated at 32 KB (110 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/walmart/refs/heads/main/openapi/walmart-marketplace-promotions-openapi-original.yml