---
updatedAt: 2026-09-08T16:01:04.000Z
---

# Update promotional price for a single item

Updates the promotional price.

Use this API to update or delete an existing promotional price as well as set up a new promotional price.

<ul><li>To set a new promotional price or update an existing one, set the pricing attribute `processMode` to `UPSERT`.</li><li>To delete a promotional price, set the pricing attribute `processMode` to `DELETE`.</li><li>To delete all promotions for a SKU, set `replaceAll` to an empty payload.</li>

For more information and usage examples, refer to the <a href="https://developer.walmart.com/us-marketplace/docs/update-promotional-price-for-a-single-item">Marketplace Promotions API Guide</a>.

# OpenAPI definition

```json
{
  "openapi": "3.0.1",
  "info": {
    "title": "Promotion Management",
    "version": "1.0",
    "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."
  },
  "x-readme": {
    "samples-languages": [
      "shell"
    ],
    "proxy-enabled": false
  },
  "servers": [
    {
      "url": "https://marketplace.walmartapis.com",
      "description": "Production URL"
    },
    {
      "url": "https://sandbox.walmartapis.com",
      "description": "Sandbox URL"
    }
  ],
  "paths": {
    "/v3/price": {
      "put": {
        "tags": [
          "Promotions"
        ],
        "summary": "Update promotional price for a single item",
        "description": "Updates the promotional price.\n\nUse this API to update or delete an existing promotional price as well as set up a new promotional price.\n\n<ul><li>To set a new promotional price or update an existing one, set the pricing attribute `processMode` to `UPSERT`.</li><li>To delete a promotional price, set the pricing attribute `processMode` to `DELETE`.</li><li>To delete all promotions for a SKU, set `replaceAll` to an empty payload.</li>\n\nFor more information and usage examples, refer to the <a href=\"https://developer.walmart.com/us-marketplace/docs/update-promotional-price-for-a-single-item\">Marketplace Promotions API Guide</a>.",
        "operationId": "updatePromotionalPrices",
        "parameters": [
          {
            "name": "promo",
            "in": "query",
            "description": "Indicates the promotional price. To retrieve the promotional prices, set this value to `true`.",
            "required": true,
            "schema": {
              "type": "boolean",
              "default": true
            }
          },
          {
            "in": "header",
            "name": "WM_SEC.ACCESS_TOKEN",
            "description": "Access token obtained from the Token API. This is required for authenticating requests to Walmart Marketplace APIs.",
            "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 that identifies each API call and is used to track and debug issues. Use a randomly generated GUID for this ID.",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "b3261d2d-028a-4ef7-8602-633c23200af6"
          },
          {
            "in": "header",
            "name": "WM_SVC.NAME",
            "description": "Specifies the name of the Walmart service being called.",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "Walmart Marketplace"
          },
          {
            "in": "header",
            "name": "WM_SANDBOX",
            "description": "Include this header to access the Marketplace dynamic sandbox environment. The dynamic sandbox is only available in the US market.",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "v2"
              ]
            },
            "example": "v2"
          }
        ],
        "requestBody": {
          "description": "SON payload specifying the SKU and promotional pricing details. To remove all promotions for a SKU, set replaceAll and provide an empty pricing array.",
          "content": {
            "application/json": {
              "schema": {
                "required": [
                  "pricing",
                  "sku"
                ],
                "type": "object",
                "properties": {
                  "offerId": {
                    "type": "string",
                    "description": "Applicable only for promotions. Indicates the promotional offer being applied."
                  },
                  "sku": {
                    "type": "string",
                    "description": "SKU of the item for which the promotional price is being updated."
                  },
                  "replaceAll": {
                    "type": "string",
                    "description": "Applicable only for promotions. Indicates whether to replace all existing promotions for the SKU.",
                    "enum": [
                      "true",
                      "false"
                    ]
                  },
                  "pricing": {
                    "type": "array",
                    "items": {
                      "required": [
                        "currentPrice",
                        "currentPriceType"
                      ],
                      "type": "object",
                      "properties": {
                        "effectiveDate": {
                          "type": "string",
                          "description": "Applicable only for promotions. Timestamp when the promotional price becomes effective.",
                          "format": "date-time"
                        },
                        "expirationDate": {
                          "type": "string",
                          "description": "Applicable only for promotions. Timestamp when the promotional price ends.",
                          "format": "date-time"
                        },
                        "promoId": {
                          "type": "string",
                          "description": "Applicable only for promotions. Unique identifier for the promotional campaign."
                        },
                        "processMode": {
                          "type": "string",
                          "description": "Applicable only for promotions. Use `UPSERT` to create or update a promotion, or `DELETE` to remove one. ",
                          "enum": [
                            "UPSERT",
                            "DELETE"
                          ]
                        },
                        "currentPriceType": {
                          "type": "string",
                          "enum": [
                            "BASE",
                            "REDUCED",
                            "CLEARANCE"
                          ]
                        },
                        "currentPrice": {
                          "type": "object",
                          "properties": {
                            "currency": {
                              "type": "string",
                              "enum": [
                                "USD",
                                "CAD"
                              ]
                            },
                            "amount": {
                              "type": "number",
                              "format": "double"
                            }
                          }
                        },
                        "comparisonPriceType": {
                          "type": "string",
                          "description": "Applicable only for promotions. The type of reference price used for comparison.",
                          "enum": [
                            "BASE"
                          ]
                        },
                        "comparisonPrice": {
                          "type": "object",
                          "properties": {
                            "currency": {
                              "type": "string",
                              "enum": [
                                "USD",
                                "CAD"
                              ]
                            },
                            "amount": {
                              "type": "number",
                              "format": "double"
                            }
                          },
                          "description": "Applicable only for promotions. The original price used to calculate savings."
                        },
                        "priceDisplayCodes": {
                          "type": "string",
                          "description": "Applicable only for promotions. Controls where the promotional price is shown to customers.",
                          "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": "Acknowledgement message for a price update. The site may take a few minutes to reflect changes.",
                      "xml": {
                        "namespace": "http://walmart.com/"
                      }
                    }
                  },
                  "xml": {
                    "name": "ItemPriceResponse",
                    "namespace": "http://walmart.com/"
                  }
                },
                "example": {
                  "ItemPriceResponse": {
                    "mart": "WALMART_US",
                    "message": "Price has been updated for the item. It may take 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": "Acknowledgement message for a price update. The site may take a few minutes to reflect changes.",
                      "xml": {
                        "namespace": "http://walmart.com/"
                      }
                    }
                  },
                  "xml": {
                    "name": "ItemPriceResponse",
                    "namespace": "http://walmart.com/"
                  }
                },
                "example": "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n<ns2:ItemPriceResponse xmlns:ns2=\"http://walmart.com/\">\n    <ns2:mart>WALMART_US</ns2:mart>\n    <ns2:sku>97964_KFTest</ns2:sku>\n    <ns2:message>Price has been updated for the item. It may take up to five minutes for this change to be reflected on the site.</ns2:message>\n</ns2:ItemPriceResponse>\n"
              }
            }
          }
        }
      }
    }
  }
}
```