Search for items in the Walmart Marketplace catalog

GET

/catalog/v4/items

GET

/seller/v1/catalog/v4/items

curl -G https://marketplace.walmart.com/seller/v1/catalog/v4/items \
     -H "Authorization: Bearer <token>" \
     -d marketplaceIds=WALMART_US

{
  "numberOfResults": 1,
  "items": [
    {
      "attributes": {},
      "identifiers": {
        "marketplaceWalmartItemId": [
          {
            "identifier": "string",
            "identifierType": "WALMART_ITEM_ID",
            "marketplaceId": "string"
          }
        ],
        "skuIdentifiers": [
          {
            "identifier": "string",
            "identifierType": "WALMART_ITEM_ID",
            "marketplaceId": "string"
          }
        ]
      },
      "images": [
        {
          "height": 1,
          "link": "string",
          "variant": "MAIN",
          "width": 1
        }
      ],
      "marketplaceId": "WALMART_US",
      "productTypes": [
        {
          "productType": "string"
        }
      ],
      "relationships": [
        {
          "childItems": [
            {
              "walmartItemId": "string"
            }
          ],
          "parentItems": [
            {
              "walmartItemId": "string"
            }
          ],
          "type": "VARIATION",
          "variationTheme": {
            "attributes": [
              "Color",
              "Size"
            ]
          }
        }
      ],
      "salesRanks": [
        {
          "categoryId": "string",
          "categoryName": "string",
          "link": "string",
          "rank": 1
        }
      ],
      "walmartItemId": "string"
    }
  ],
  "pagination": {
    "nextToken": "string",
    "previousToken": "string"
  },
  "refinements": {
    "classificationRefinements": [
      {
        "categoryId": "string",
        "displayName": "string",
        "numberOfResults": 1
      }
    ],
    "departments": [
      {
        "departmentId": "string",
        "displayName": "string"
      }
    ]
  }
}

Search the Walmart Marketplace catalog using keywords, WalmartItemId, GTIN, UPC, or seller SKU. Returns matching catalog items.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Query parameters

keywordsstringOptional<=500 characters

Keyword search terms

walmartItemIdsstringOptional

Comma-separated Walmart Item IDs (14-digit). Max 20.

sellerSkustringOptional<=50 characters

Seller-defined SKU

gtinstringOptionalformat: "^\d{14}$"

Global Trade Item Number (14-digit)

upcstringOptionalformat: "^\d{12}$"

Universal Product Code (12-digit)

marketplaceIdslist of enumsRequired

Walmart marketplace identifiers. Use WALMART_US for the US marketplace.

Allowed values:

includedDatalist of enumsOptional

Data sections to include in the response

pageSizeintegerOptional1-20Defaults to 10

Number of results per page (1–20). Known limitation: The PIQS keyword search backend hard-caps results at 40 items per call regardless of this value.

pageTokenstringOptional

Token for the next page of results, obtained from pagination.nextToken in a previous response. Known limitation: Cursor-based pagination is not currently supported for keyword search. The PIQS search backend (/v3/items/walmart/search) does not return a nextCursor and does not honour this parameter. Results are capped at 40 items per call. Reserved for future use once PIQS exposes pagination support.

Token for the next page of results, obtained from `pagination.nextToken` in a previous response. **Known limitation:** Cursor-based pagination is not currently supported for keyword search. The PIQS search backend (`/v3/items/walmart/search`) does not return a `nextCursor` and does not honour this parameter. Results are capped at 40 items per call. Reserved for future use once PIQS exposes pagination support.

Response headers

x-walmart-request-idstringOptional

Unique identifier for the request (for support tracing)

Response

Success

numberOfResultsinteger

Total number of matching listings items

itemslist of objects

paginationobjectOptional

Errors

400

Bad Request Error

403

Forbidden Error

404

Not Found Error

429

Too Many Requests Error

500

Internal Server Error