Skip to content
Scrappa Get API key
H-E-B API 1 credit / request

H-E-B Search API Documentation

GET https://scrappa.co/api/heb/search

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.

H-E-B Search API Documentation 1 credit / request

Endpoint

Request preview
GET
https://scrappa.co/api/heb/search
Auth header
x-api-key
Cost
1 credit / request
query = coffee shops
Response preview
200 OK
{
    "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",
...

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.

query string Required

Search text, 1 to 120 characters, for example milk.

Example value coffee shops
storeId integer Optional

Public H-E-B store id, default 590.

Example value 10
shoppingContext string Optional

CURBSIDE_PICKUP or CURBSIDE_DELIVERY.

Example value example
category string Optional

Numeric category id from the categories block of a search response.

Example value example
sortBy string Optional

SCORE, PRICE or PRODUCT_NAME.

Example value example
sortDirection string Optional

ASC or DESC.

Example value example
cursor string Optional

The next_cursor of the previous response.

Example value 0
page integer Optional

Page number, 1 based. Needs a cursor when above 1.

Example value 1

Response Schema

Example response fields are illustrative; inspect the JSON before integrating.

Example response fields

Scan these fields before integrating.

data meta success
JSON Response
200 OK
{
    "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.

422

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"
}
503

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.