Developer Portal
Walmart Developer
HomeSDKsAPI ReferenceContext Plugin
Catalog itemsCatalog

Search for items in the Walmart Marketplace catalog

GET
/catalog/v4/items

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

Authorization

walletAuth
AuthorizationBearer <token>

In: header

Query Parameters

keywords?string

Keyword search terms

Lengthlength <= 500
walmartItemIds?string

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

sellerSku?string

Seller-defined SKU

Lengthlength <= 50
gtin?string

Global Trade Item Number (14-digit)

Match^\d{14}$
upc?string

Universal Product Code (12-digit)

Match^\d{12}$
marketplaceIds*array<string>

Walmart marketplace identifiers. Use WALMART_US for the US marketplace.

Itemsitems <= 1
includedData?array<>

Data sections to include in the response

pageSize?integer

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.

Range1 <= value <= 20
Default10
pageToken?string

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 Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/catalog/v4/items?marketplaceIds=string"
{  "numberOfResults": 0,  "pagination": {    "nextToken": "string",    "previousToken": "string"  },  "refinements": {    "departments": [      {        "departmentId": "string",        "displayName": "string"      }    ],    "classificationRefinements": [      {        "categoryId": "string",        "displayName": "string",        "numberOfResults": 0      }    ]  },  "items": [    {      "walmartItemId": "string",      "marketplaceId": "string",      "attributes": {        "property1": [          {            "displayValue": "string",            "value": {},            "language": "en_US"          }        ],        "property2": [          {            "displayValue": "string",            "value": {},            "language": "en_US"          }        ]      },      "identifiers": {        "marketplaceWalmartItemId": [          {            "identifierType": "WALMART_ITEM_ID",            "identifier": "string",            "marketplaceId": "string"          }        ],        "skuIdentifiers": [          {            "identifierType": "WALMART_ITEM_ID",            "identifier": "string",            "marketplaceId": "string"          }        ]      },      "images": [        {          "variant": "MAIN",          "link": "http://example.com",          "height": 0,          "width": 0        }      ],      "productTypes": [        {          "productType": "string"        }      ],      "salesRanks": [        {          "categoryId": "string",          "rank": 0,          "categoryName": "string",          "link": "http://example.com"        }      ],      "relationships": [        {          "type": "VARIATION",          "childItems": [            {              "walmartItemId": "string"            }          ],          "parentItems": [            {              "walmartItemId": "string"            }          ],          "variationTheme": {            "attributes": [              "Color",              "Size"            ]          }        }      ]    }  ]}

Dynamic Client Registration (RFC 7591) POST

Registers a Solution Provider client and returns its `client_id` (RFC 7591). Lets Solution Providers onboard without manual registration. Public clients set `token_endpoint_auth_method: none` (no secret; PKCE required). Confidential clients receive a `client_secret`. `redirect_uris` are validated and later enforced by exact match at `/auth/v4/authorize`. Proxied to Walmart IAM's registration endpoint (/). RFC 7592 registration management (read/update/delete via a `registration_access_token`) is not offered in this version.

Retrieve details for an item in the Walmart Marketplace catalog GET

Next Page