H-E-B Search API searches grocery products on heb.com. Each item has the name, brand, size, price, regular and sale price, unit price, full-size image, availability and promotion flags. Prices are in US dollars.
Send query and optionally a public storeId (default 590), shoppingContext, sortBy, sortDirection and a category. For a later page, send the next_cursor of the previous response as cursor, with page one higher. A page above 1 without a cursor answers 422. Unknown parameters also answer 422. Accepted filter values are listed in the filters, categories and sort_options blocks of the response.
Product ids pass unchanged to the product route. Use id from a search result. A search without hits returns an empty list. Costs 1 credit per successful request with results. Empty results and failed requests are free.
Run this endpoint
Endpoint
Parameters
Start with the required fields, then add optional filters only when your use case needs them.
Runnable path
1 required parameter needed before sending a request.
7 optional filters available.
string
Required
Search text, 1 to 120 characters, for example milk.
coffee shops
integer
Optional
Public H-E-B store id, default 590.
10
string
Optional
CURBSIDE_PICKUP or CURBSIDE_DELIVERY.
example
string
Optional
Numeric category id from the categories block of a search response.
example
string
Optional
SCORE, PRICE or PRODUCT_NAME.
example
string
Optional
ASC or DESC.
example
string
Optional
The next_cursor of the previous response.
0
integer
Optional
Page number, 1 based. Needs a cursor when above 1.
1
Response Schema
Example response fields are illustrative; inspect the JSON before integrating.
Example response fields
Scan these fields before integrating.
data
meta
success
{
"data": {
"page": 1,
"count": 1,
"items": [
{
"id": "314124",
"name": "H-E-B Whole Milk Gallon",
"size": "1 gal",
"unit": "fl oz",
"brand": "H-E-B",
"image": "https://images.heb.com/is/image/HEBGrocery/000314124-1",
"price": 3.29,
"category": "Dairy & Eggs",
"currency": "USD",
"position": 1,
"unit_price": 0.03,
"availability": "CURBSIDE_PICKUP",
"regular_price": 3.29
}
],
"query": "milk",
"total": 325,
"store_id": 590,
"next_cursor": "eyJvZmZzZXQiOjUwfQ",
"has_next_page": true,
"shopping_context": "CURBSIDE_PICKUP"
},
"meta": {
"credits": 1,
"billable": true,
"endpoint_family": "search"
},
"success": true
}
Errors
Handle these documented responses before retrying or showing customer-facing failures.
Validation Error
A required parameter, a value or an unknown filter is invalid. This response is not billable.
{
"errors": {
"query": [
"Unsupported search parameter: savings."
]
},
"message": "The request validation failed"
}Upstream Unavailable
H-E-B could not be reached after a fresh-exit retry. This response is not billable.
{
"meta": {
"billable": false,
"retryable": true,
"endpoint_family": "search"
},
"error": {
"code": "UPSTREAM_UNAVAILABLE",
"message": "H-E-B could not be reached. Please retry shortly."
},
"success": false
}Generate Code with AI
Copy a ready-made prompt with all the endpoint details, parameters, and example responses. Paste it into ChatGPT, Claude, or any AI assistant to instantly generate working code.
Try It Live
Test this endpoint in our interactive playground with real data.