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": { "processMode": "REPLACE", "subset": "EXTERNAL", "locale": "en", "sellingChannel": "mpsetupbymatch", "version": "4.2" }, "MPItem": [ { "Item": { "sku": "2xxxx", "productIdentifiers": { "productIdType": "GTIN", "productId": "62235xxxxxxx" }, "ShippingWeight": 6.94, "price": 149.9, "condition": "New", "productCategory": "Large Appliances" } } ] }'

Example payload (MP_ITEM_MATCH v4.2)

{ "MPItemFeedHeader": { "processMode": "REPLACE", "subset": "EXTERNAL", "locale": "en", "sellingChannel": "mpsetupbymatch", "version": "4.2" }, "MPItem": [ { "Item": { "sku": "2xxxx", "productIdentifiers": { "productIdType": "GTIN", "productId": "62235xxxxxxx" }, "ShippingWeight": 6.94, "price": 149.9, "condition": "New", "productCategory": "Large Appliances" } } ]
}

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.