Pricing and promotional pricing management API overview

Use the Pricing and promotional pricing management APIs to create, update, or remove promotional pricing for a SKU. Promotional pricing must follow the rules outlined below. For more information about the promotional pricing, refer to Seller Help: Promotion Rules .

Promotion rules

• A maximum of 10 promotions can be configured for a single SKU.
• The promotion start time must be at least four hours from the current time.
• A promotion cannot be cancelled within four hours of its scheduled start time. If a promotion is about to begin, allow it to start and then delete it.
• The end date must be later than the start date.
• The promotion duration cannot exceed 180 days.
• Promotions for the same SKU cannot have overlapping date ranges.

Using pricing and promotion fields

Create a promotion

To create a promotion:

• Set promotionSettingAction to Create
• Provide the sku
• Provide the promotionPrice
• Provide promotionPriceStartDateTime (UTC)
• Provide promotionPriceEndDateTime (UTC)

Optional:

• promotionType
  • Reduced – Temporary price reduction (minimum duration: 14 days)
  • Clearance – Used when an item is being discontinued or liquidated
• promotionPlacement
  • MAP Cart – Hides the price until the customer clicks Add to cart (US only)
• msrp – Used for strikethrough pricing (US only)

A Reduced promotion must run for a minimum of 14 days.

Delete a promotion

To delete an existing promotion:

• Set promotionSettingAction to Delete
• Provide the sku
• Provide the exact promotionPriceStartDateTime
• Provide the exact promotionPriceEndDateTime

The start and end date/time must exactly match the promotion currently configured for the SKU.

Replace all promotions

To remove all existing promotions (and optionally create new ones in the same request):

• Set promotionSettingAction to ReplaceAll
• Provide the sku

If creating new promotions in the same request, also include:

• promotionPrice
• promotionPriceStartDateTime
• promotionPriceEndDateTime

Reference guide

This guide explains how to use the Pricing API with practical examples and step-by-step instructions to integrate price management into your solution. For full technical details, including endpoints, parameters, and brief descriptions, refer to the Walmart Promotions API reference.

Prerequisites

Before using the Walmart Marketplace APIs, ensure that you have:

• Seller or approved Solution Provider access to Walmart Marketplace APIs.
• Retrieve API keys (clientId and clientSecret) from the Developer Portal and use the keys to call Marketplace APIs.
• OAuth 2.0 authentication is required to access the Walmart Marketplace APIs. Ensure that you have obtained the necessary credentials and tokens before making API requests. For more information, refer to OAuth 2.0 authorization.

JSON schema files

Use the following link to download the Pricing and promotional pricing management management XSDs.

 Price&PromotionJSON.zip