---
updatedAt: 2026-06-01T18:25:31.000Z
---

# 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](https://marketplacelearn.walmart.com/guides/Growth%20opportunities/Promotions/Promotional-pricing:-Overview) .

## Promotion rules

* A maximum of **10 promotions** can be configured for a single SKU.
* The promotion start time must be at least **30 minutes from the current time (UTC time)**.
* A promotion can be deleted at any time, even if it is active.
* 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](/us-marketplace/reference/updatepromotionalprices).

## 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 ](https://developer.walmart.com/account/generateKey)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](https://developer.walmart.com/us-marketplace/docs/oauth-20-authorization).

## JSON schema files

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

 [Price\&PromotionJSON.zip](/file/mp/us/PricePromotionJSON.zip)

## Rate limits

If you submit too many feeds in a short period of time, you may exceed Walmart’s rate limits and receive HTTP 429 (Too Many Requests) responses. For more details on throttling and best practices, refer to the [Rate Limiting Guide](/us-marketplace/docs/rate-limiting).