Create an offer for an existing Walmart item

Offer setup by match

The offer setup by match workflow lets you create an offer by matching an existing Walmart catalog item. Use the bulk item setup API with feedType=MP_ITEM_MATCH to submit an offer setup by match feed file. Walmart uses the identifiers in your feed to find a matching catalog item and reuse its item setup information, so you can create your offer without submitting a full item setup payload. This reduces the amount of data you need to provide and helps streamline offer setup when a match is found.

Use cases

  • Create offers for items that already exist in the Walmart catalog without performing a full item setup.
  • Reduce the amount of data you need to submit by providing only offer-specific and match-specific attributes (for example, SKU, condition, and price).
  • Submit multiple SKUs in a single feed file to create offers in bulk.
  • Streamline offer setup by reusing existing Walmart catalog item information when a match is found.
  • Fall back to full item setup if a matching catalog item is not found.

Reference guide

This guide explains how to use the offer setup by match workflow to create an offer for an existing Walmart catalog item.

For full technical details, including endpoints, parameters, and brief descriptions, refer to the Bulk Item Setup API Reference.

Endpoint

POST https://marketplace.walmartapis.com/v3/feeds?feedType=MP_ITEM_MATCH

Request body

The request body must include either:

  • a feed file uploaded as multipart/form-data (file), or
  • an inline JSON payload (application/json) structured for the MP_ITEM_MATCH feed type.

Request sample

Option 1: Upload a file (recommended for larger feeds)

curl --request POST \ --url "https://marketplace.walmartapis.com/v3/feeds?feedType=MP_ITEM_MATCH" \ --header "WM_SEC.ACCESS_TOKEN: <ACCESS_TOKEN>" \ --header "WM_QOS.CORRELATION_ID: <UUID>" \ --header "WM_SVC.NAME: Walmart Marketplace" \ --header "accept: application/json" \ --header "content-type: multipart/form-data" \ --form "file=@./mp_item_match.json"

Option 2: Send an inline JSON payload

curl --request POST \ --url "https://marketplace.walmartapis.com/v3/feeds?feedType=MP_ITEM_MATCH" \ --header "WM_SEC.ACCESS_TOKEN: <ACCESS_TOKEN>" \ --header "WM_QOS.CORRELATION_ID: <UUID>" \ --header "WM_SVC.NAME: Walmart Marketplace" \ --header "accept: application/json" \ --header "content-type: application/json" \ --data '{ "MPItemFeedHeader": { "businessUnit": "WALMART_US", "locale": "en", "version": "5.0.20250121-19_24_23-api" }, "MPItem": [ { "Item": { "sku": "00649081xxxxxx", "condition": "Pre-Owned: Fair", "mainImageUrl": "https://i5-qa.walmartimages.com/asr/549ecbe9-c874-475b-87d8-5e4cb19934ec.8f5d70e62bd0bb8abc6772c9ef1694e0.jpeg", "productIdentifiers": { "productIdType": "GTIN", "productId": "00469710xxxxxx" }, "ShippingWeight": 1, "price": 1 } } ] }'

Example payload (MP_ITEM_MATCH v4.8)

{ "MPItemFeedHeader": { "sellingChannel": "marketplace", "processMode": "REPLACE", "subset": "EXTERNAL", "locale": "en", "version": "4.8", "subCategory": "home_other" }, "MPItem": [ { "Orderable": { "sku": "TRVAL28726", "condition": "New", "productIdentifiers": { "productIdType": "GTIN", "productId": "06146190200012" }, "productName": "Bocaoying 3 Pcs Chef Hats for Adults, Adjustable Elastic Chef Cap, Kitchen Bakers Hat Cooking Cap Funny Chef Gifts for Men Women(Black, White, Red)", "brand": "Saukore", "price": 1, "stateRestrictions": [ { "stateRestrictionsText": "None" } ], "ShippingWeight": 1, "electronicsIndicator": "No", "batteryTechnologyType": "Does Not Contain a Battery", "chemicalAerosolPesticide": "No", "shipsInOriginalPackaging": "No", "MustShipAlone": "No" }, "Visible": { "Home Decor, Kitchen, & Other": { "shortDescription": "A Little Bit Snug; These chef hats for adults are about 11.2 inches/ 28.4 cm wide, and 2 inches/ 5 cm high, for a total height of 4.9 inches/ 12.4 cm, and they have elastic in the headband that helps give it a little stretch, one size fits most adults. Lightweight and Comfortable. These adjustable elastic bakery hats are made of polyester fabric that is lightweight, soft and comfortable for long hours of wear; In addition, these adjustable cooking hats are fade resistant and will remain vibrant after washing. Traditional Cook's Hat. Bakers hat features a traditional, tall, pleated design that is simple and classic, looks cute and professional, and can help keep your head cool and your hair covered in hot and stressful environments. Practical Cooking Accessories. Cooking chef caps are suitable for many occasions, such as catering colleges, schools, restaurants, families, etc., and they can also be worn with aprons to keep you clean while cooking. Multicolored Fabric Chef Hat. The package comes with 3 pieces of tall chefs hats in 3 colors, namely, black, white and red, 1 pieces of each color, ideal for matching with your chef's uniforms to complete your outfit.", "mainImageUrl": "https://i5-qa.walmartimages.com/asr/9e9d04d1-6520-448e-b336-f40b7fb98707.c4c99539377709c2a9e332558177be8b.jpeg", "productSecondaryImageURL": [ "https://i5.walmartimages.com/asr/f6bc9d4c-1b93-4d1a-ac26-275d1be0e820.c91145d323e950d239c14dc041ee9098.jpeg", "https://i5.walmartimages.com/asr/bd90447a-ddb1-4bbe-8e7e-d97f1c055086.6fab578476f6d208d9795bfbebb26153.jpeg", "https://i5.walmartimages.com/asr/7cd2651b-0193-4943-9718-e1512043cf0b.91ec6c19f1c75f9c4c625b074f56ff59.jpeg", "https://i5.walmartimages.com/asr/13427bea-8be9-4673-8f66-98cde23a7f50.9a75ecef4ae538193796315e1d5dfbf0.jpeg", "https://i5.walmartimages.com/asr/3350c7b8-096e-499a-a2a0-0cde8a4fd993.b865c86f70317a4579fd052c20acd7ed.jpeg", "https://i5.walmartimages.com/asr/4cb4498f-0737-454b-a330-ab092bb892e4.40976faea93cec923c0f6fd821fa237f.jpeg", "https://i5.walmartimages.com/asr/a47bdcf5-c589-4c49-993c-433f668614d4.16cab343d9c3f18d44e4e26a32d6c8f1.jpeg" ], "keyFeatures": [ "Adult chef hat. Color: black, red, white Material: Polyester 65% Cotton 35% With elastic in the back One size fits most. Adjustable chef hat. Comfortable to wear. A practical gift for the kitchen fanatics. Machine wash with like colors, tumble try low. Suitable for catering colleges, schools, restaurants, pubs, cafes, commercial, kitchens, hotels etc." ], "msrp": 13.99, "manufacturer": "Saukore", "countPerPack": 1, "count": "3", "pieceCount": 3, "color": [ "Black, White, Red" ], "homeDecorStyle": "Kitchen", "fabricCareInstructions": [ "Machine wash with like colors, tumble try low" ], "gender": "Unisex", "features": [ "Adjustable Fit" ] } } } ]
}

Modify your code

  1. Find the item you want to sell

    • Use item search API to find the catalog item (ideally using identifiers like UPC/GTIN).
  2. Choose your match identifier

    • Prefer identifiers like GTIN/UPC when available to improve match likelihood.
  3. Build the MP_ITEM_MATCH feed file

    • Use the schema structure that matches your market/spec version (see examples above).
    • Include only the fields required for matching and your offer-specific data.
    • Send required headers and any optional headers as needed.
  4. Submit the feed

    • Upload the feed file using POST /v3/feeds?feedType=MP_ITEM_MATCH as multipart/form-data and include the feed file in the file form field (for example, --form 'file=@<filename>.json').
  5. Track processing

    • Use the returned feedId to check feed status and item-level outcomes. Track processing results using the feed item status API in your integration.
  6. Handle non-matches

    • If a match is not found (or you want to provide your own content), submit a full item setup feed using the Bulk Item Setup API with MP_ITEM feed type.

Minimum required fields for sending an inline JSON payload

When using offer setup by match, you generally provide only the offer-specific attributes:

  • SKU: Seller-defined identifier for your offer.
  • Condition: New or one of the supported non-new closed-list conditions (non-new conditions are available only for program-eligible sellers).
  • Main Image URL: Conditionally required for these conditions: Remanufactured, Pre-Owned: Like New, Pre-Owned: Good, Pre-Owned: Fair, or New with defects.
  • Shipping Weight: The weight of the item.
  • Price: The price of the item.

Response sample (200)

{ "feedId": "F129C19240844B97A3C6AD8F1A2C4997@AU8BAQA"
}

Result

After a successful call (200):

  • You receive a feedId to track processing and item-level outcomes.
  • Walmart checks whether each submitted item matches an existing catalog item. If a match is found, the item can be set up without submitting full catalog content.

Next steps

  1. Check processing results using your feed status workflow (for example, the Feed Item Status API) to determine whether a match was found for each SKU.
  2. If a match is found, confirm the offer appears in your catalog and validate key offer attributes (price, condition, etc.).
  3. If a match is not found (or you want to provide your own content), submit a full setup feed using the Bulk Item Setup API (for example, MP_ITEM, MP_WFS_ITEM, or MP_MAINTENANCE depending on your use case).
  4. Follow the bulk feed workflow steps outlined in the Item Management API overview (upload → track status → review errors → retry failed records).