Guides
My Account

Retire an item

The Retire an item API lets you permanently retire an item from the Walmart Catalog using your seller SKU. This is useful when an item is discontinued, invalid, or was created for testing and should no longer exist in the catalog. A successful API call confirms the retirement request was accepted; the catalog update itself can take up to 48 hours.

Use cases

  • Discontinue a product permanently so it no longer appears or is sold via the catalog.
  • Remove invalid or duplicate listings tied to a SKU that should not exist.
  • Clean up test SKUs after integration testing.
  • Catalog maintenance when migrating SKUs or ending a product lifecycle.

Benefits

  • Permanent retirement workflow: Designed specifically for permanently retiring an item identified by SKU.
  • Simple integration: One call using a standard HTTP method (DELETE) plus a small set of headers.
  • Operational traceability: Correlation IDs support debugging and support escalation.
  • Clear acknowledgement messaging: Response includes a human-readable confirmation message.

Reference guide

This guide explains how to use the Retire an item operation to permanently retire a single item from the Walmart Catalog using its seller-defined SKU.

For full technical details, including endpoints, parameters, and brief descriptions, refer to the Retire an item API Reference.

Endpoint

DELETE https://marketplace.walmartapis.com/v3/items/{sku}

Path parameter

  • sku (required, string): Seller-defined unique SKU that identifies the item. If the SKU contains reserved/special characters, URL-encode it in the path. These characters need encoding - :, /, ?, #, [, ], @, !, $, &, ', (, ), *, +, ,, ;, =, and %.

Request sample

curl --request DELETE \ --url https://marketplace.walmartapis.com/v3/items/sku \ --header 'WM_QOS.CORRELATION_ID: b3261d2d-028a-4ef7-8602-633c23200af6' \ --header 'WM_SEC.ACCESS_TOKEN: eyJraWQiOiIxNWNhNGIyYi0yODVjLTQ0ZDUtYmExNC05ZDk1NTlkZmUwNjgiLCJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiZGlyIn0.....' \ --header 'WM_SVC.NAME: Walmart Marketplace' \ --header 'WM_CONSUMER.CHANNEL.TYPE: <consumer-channel-type>' \ --header 'accept: application/json'

import requests url = "https://marketplace.walmartapis.com/v3/items/sku" headers = { "WM_QOS.CORRELATION_ID": "b3261d2d-028a-4ef7-8602-633c23200af6", "WM_SEC.ACCESS_TOKEN": "eyJraWQiOiIxNWNhNGIyYi0yODVjLTQ0ZDUtYmExNC05ZDk1NTlkZmUwNjgiLCJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiZGlyIn0.....", "WM_SVC.NAME": "Walmart Marketplace", "WM_CONSUMER.CHANNEL.TYPE": "<consumer-channel-type>", "accept": "application/json",
} response = requests.delete(url, headers=headers, timeout=30)
print("Status:", response.status_code)
print(response.text)

Modify your code

  1. Identify the SKU you want to retire (seller-defined, unique per item).
  2. Replace the {sku} segment in the URL with your SKU (item being retired) and ensure the SKU is URL-encoded if it contains reserved characters characters like /, ?, #, or %.
  3. Send required headers, including:
    • WM_SEC.ACCESS_TOKEN
    • WM_QOS.CORRELATION_ID
    • WM_SVC.NAME
    • WM_CONSUMER.CHANNEL.TYPE (use the value provided during onboarding, if applicable)
  4. You can customize the response format using the accept header (allowed values: application/json, application/xml).
    1. To request JSON (current sample):
      --header 'accept: application/json'
    2. To request XML:
      Change the header to:
      --header 'accept: application/xml'
  5. Review the response for the returned sku and confirmation message. Treat the response as confirmation of submission; catalog retirement may take additional time to complete.

Response sample

{ "sku": "97964_KFTest", "message": "Thank you. Your item has been submitted for retirement from Walmart Catalog. Please note that it can take up to 48 hours for items to be retired from our catalog.", "additionalAttributes": null, "errors": null
}

Results

After a successful call:

  • The API returns the SKU and a confirmation message acknowledging the retirement submission.
  • The item retirement may take time to reflect in the catalog (your message indicates it can take up to 48 hours).
  • In the provided sample, errors is null, indicating the request itself was accepted without reported issues.

If the request fails, the API reference indicates you may see:

  • 400 (Bad Request)
  • 500 (Internal Server Error)

Next steps

  • Refer to the API reference documentation to confirm required headers, supported accept values (application/json, application/xml), response fields, and the latest error/status code behavior.
  • Log the correlation ID per request for troubleshooting and support.

Updated 3 days ago