Skip to content
Scrappa Get API key
Instacart API 1 credit / request

Instacart Stores API Documentation

GET https://scrappa.co/api/instacart/stores

Instacart Stores API lists grocery retailers available at a US ZIP. Each store has its shop id, retailer id, slug, name, categories, logo and delivery ETA when the source publishes one.

Send a five-digit zip from the supported set (currently 10016). Other ZIPs answer 422 without an upstream call. The source market must be a real US city and state for that ZIP. Costs 1 credit per successful request with results. Failed requests and empty results are free.

Instacart Stores API Documentation 1 credit / request

Endpoint

Request preview
GET
https://scrappa.co/api/instacart/stores
Auth header
x-api-key
Cost
1 credit / request
zip = example
Response preview
200 OK
{
    "data": {
        "count": 2,
        "market": {
            "city": "New York",
            "state": "NY",
            "postal_code": "10016"
        },
        "stores": [
            {
                "logo": "https://example.invalid/logo.png",
                "name": "Safeway",
                "slug": "safeway",
                "shop_id": "37447",
...

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.

zip string Required

Required supported US ZIP (currently 10016); other ZIPs answer 422; validity gate only, not echoed back

Example value example

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": {
        "count": 2,
        "market": {
            "city": "New York",
            "state": "NY",
            "postal_code": "10016"
        },
        "stores": [
            {
                "logo": "https://example.invalid/logo.png",
                "name": "Safeway",
                "slug": "safeway",
                "shop_id": "37447",
                "categories": [
                    "Grocery"
                ],
                "retailer_id": 118,
                "delivery_eta": {
                    "eta_seconds": 3600,
                    "delivery_string": "Delivery in 1 hour"
                }
            }
        ],
        "requested_zip": "10016"
    },
    "meta": {
        "credits": 1,
        "billable": true,
        "endpoint_family": "stores"
    },
    "success": true
}

Errors

Handle these documented responses before retrying or showing customer-facing failures.

422

Market Mismatch

The egress market does not match the requested ZIP. No data was labelled with that ZIP. This response is not billable.

{
    "meta": {
        "billable": false,
        "retryable": false,
        "endpoint_family": "stores"
    },
    "error": {
        "code": "MARKET_MISMATCH",
        "message": "The egress market does not match the requested ZIP. No data was labelled with that ZIP."
    },
    "success": false
}
422

Validation Error

The ZIP is missing or invalid. This response is not billable.

{
    "errors": {
        "zip": [
            "The ZIP is five digits, e.g. zip=10016."
        ]
    },
    "message": "The request validation failed"
}
503

Upstream Unavailable

Instacart could not be reached. This response is not billable. Retry shortly.

{
    "meta": {
        "billable": false,
        "retryable": true,
        "endpoint_family": "stores"
    },
    "error": {
        "code": "UPSTREAM_UNAVAILABLE",
        "message": "Instacart 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.