# Gopuff API

> Gopuff collections, products, product details and search (unverified)

- Vendor: `gopuffapi` · version 1.0 · category E-commerce · tags gopuff api, gopuff products api, gopuff search api, convenience delivery api, gopuff catalog api, instant delivery data api
- Datasource: custom HTTP routes
- Marketplace page: https://apiclay.com/api/gopuffapi
- This document: https://apiclay.com/docs/gopuffapi.md
- OpenAPI 3.1: https://apiclay.com/api/gopuffapi/openapi.json
- MCP: connect https://api.apiclay.com/v1/mcp (see https://apiclay.com/llms.txt), then `apiclay_describe_api` with vendor `gopuffapi`
- Updated: 2026-11-18

## About

## Gopuff API

Gopuff's home-page collections, category subcollections and products with prices and stock, product details, keyword search, and the partner stock/price API (bring your own partner credentials).

Data comes from **gopuff.com** (https://www.gopuff.com). Every route below calls the site's own endpoint directly and returns the upstream response unchanged.

Typical flow: `/menus` -&gt; `/categories` -&gt; `/products` -&gt; `/product` (or `/search`)

`contentParams` is the Gopuff location (delivery zone) id, e.g. `434`.

### Routes

#### POST `/menus` - Menus (home page collections)
The top-level collections shown on Gopuff's home page.

No parameters.

Returns (fields the source code reads; not yet verified live):
- `data.templateEntities[].collectionRef.collection`: `id` (category id, e.g. `txe0Kwob`), `name`, `destination`, `children[]`

#### POST `/categories` - Categories (subcategory links)
The subcategories of a category.

| Param | In | Type | Required | Description |
|---|---|---|---|---|
| variables.route | body (JSON) | string | yes | `/us/c/`, e.g. `/us/c/txe0Kwob`. |
| variables.contentParams | body (JSON) | string | yes | Location id, e.g. `1`. |
| variables.apiVersion | body (JSON) | string | yes | `v2`. |

Returns (fields the source code reads; not yet verified live):
- `data.view.content.content[0].collection[]`: subcategories with `linkId` (id for `/products`) and `linkText` (name)

#### POST `/products` - Products (category products)
Products in a category at a location, with price and stock.

| Param | In | Type | Required | Description |
|---|---|---|---|---|
| variables.route | body (JSON) | string | yes | `/us/c/`. |
| variables.contentParams | body (JSON) | string | yes | Location id, e.g. `434`. |
| variables.fulfillmentType | body (JSON) | string | no | `fulfillment_delivery` or `fulfillment_pickup`. |
| variables.apiVersion | body (JSON) | string | yes | `v2`. |

Returns (fields the source code reads; not yet verified live):
- `data.view.content.content[1].collection[]`: `id`, `title`, `brand`, `price`, `offer` (sale price), `size`, `unitSize.measurement`, `quantity` (stock), `availability.availableNow`, `tileImages[].url`, `destination` (product path)

#### POST `/product` - Product (product details)
One product at a location.

| Param | In | Type | Required | Description |
|---|---|---|---|---|
| variables.route | body (JSON) | string | yes | `/us/p/p/p?contentSection=product` (product id from `/products`). |
| variables.contentParams | body (JSON) | string | yes | Location id, e.g. `434`. |
| variables.fulfillmentType | body (JSON) | string | no | `fulfillment_delivery` or `fulfillment_pickup`. |
| variables.apiVersion | body (JSON) | string | yes | `v2`. |

Returns (fields the source code reads; not yet verified live):
- `data.view.content.product`: `id`, `title`, `description`, `price`, `offer`, `quantity`, `availability`, `productDetailImages[]`, `sizes[]`, `modifications[]`

#### POST `/search` - Search (keyword)
Keyword search in a delivery zone.

| Param | In | Type | Required | Description |
|---|---|---|---|---|
| variables.route | body (JSON) | string | yes | `US/s?q=`, e.g. `US/s?q=coke`. |
| variables.contentParams | body (JSON) | string | yes | Delivery zone id, e.g. `432`. |

Returns (fields the source code reads; not yet verified live):
- `data.view.content.content[0].collection[]`: products with `id`, `title`, `price`, `quantity`, `unitSize`, `image.src[]`, `categoryId` (a second collection holds suggestions when nothing matches)

#### GET `/partner_products` - Partner products (stock and price by product id)
Gopuff's partner API: stock and price for product ids at a location. Needs your own Gopuff partner credentials.

| Param | In | Type | Required | Description |
|---|---|---|---|---|
| location_id | query | string | yes | Gopuff location id, e.g. `434`. |
| product_ids | query | string | yes | Up to 300 comma-separated product ids. |
| Gopuff-Partner | header | string | yes | Your Gopuff partner id. |
| Gopuff-Access-Token | header | string | yes | Your Gopuff partner access token. |

Returns (fields the source code reads; not yet verified live):
- `products[]`: `id`, `quantity`, `price`

### Not yet available

| Endpoint | Why |
|---|---|
| customizations | the legacy prodcat.gopuff.com API no longer resolves |

### Caveats

- These routes were written from MealMe's source code and have not been tested live yet (the site blocks plain requests from the test machine).
- The source site uses bot protection (Cloudflare); calls may be blocked until that is handled.
- Upstream calls change over time (embedded keys, field names). Verify responses before relying on them.
- Not affiliated with gopuff.com.

## Pricing

- Pay as you go: 0.0012 credits/request
- Trial: 1 free requests per buyer
- Billing order: trial requests -> subscribed plan requests -> pay as you go. 1 credit's USD value is shown on the marketplace page.

## HTTP routes

Only the public, buyer-facing parts of each route are listed; vendor-side credentials stay on the gateway.

### POST /menus — Menus (home page collections)
- Gateway: `POST https://api.apiclay.com/v1/api/gopuffapi/menus`
- Upstream proxy: ApiClay proxy paid by the vendor (data cap 2 MB per call). Fetched through an ApiClay proxy paid by the vendor; a response larger than the route's data cap fails with 502 and is refunded in full.

### POST /categories — Categories (subcategory links)
- Gateway: `POST https://api.apiclay.com/v1/api/gopuffapi/categories`
- Body sample (JSON):

```json
{"variables": {"apiVersion": "v2", "contentParams": "1", "route": "/us/c/txe0Kwob"}}
```

- Upstream proxy: ApiClay proxy paid by the vendor (data cap 2 MB per call). Fetched through an ApiClay proxy paid by the vendor; a response larger than the route's data cap fails with 502 and is refunded in full.

### POST /products — Products (category products)
- Gateway: `POST https://api.apiclay.com/v1/api/gopuffapi/products`
- Body sample (JSON):

```json
{"variables": {"apiVersion": "v2", "contentParams": "434", "fulfillmentType": "fulfillment_delivery", "route": "/us/c/txe0Kwob"}}
```

- Upstream proxy: ApiClay proxy paid by the vendor (data cap 2 MB per call). Fetched through an ApiClay proxy paid by the vendor; a response larger than the route's data cap fails with 502 and is refunded in full.

### POST /product — Product (product details)
- Gateway: `POST https://api.apiclay.com/v1/api/gopuffapi/product`
- Body sample (JSON):

```json
{"variables": {"apiVersion": "v2", "contentParams": "434", "fulfillmentType": "fulfillment_delivery", "route": "/us/p/p12345/p12345?contentSection=product"}}
```

- Upstream proxy: ApiClay proxy paid by the vendor (data cap 2 MB per call). Fetched through an ApiClay proxy paid by the vendor; a response larger than the route's data cap fails with 502 and is refunded in full.

### POST /search — Search (keyword)
- Gateway: `POST https://api.apiclay.com/v1/api/gopuffapi/search`
- Body sample (JSON):

```json
{"variables": {"contentParams": "432", "route": "US/s?q=coke"}}
```

- Upstream proxy: ApiClay proxy paid by the vendor (data cap 2 MB per call). Fetched through an ApiClay proxy paid by the vendor; a response larger than the route's data cap fails with 502 and is refunded in full.

### GET /partner_products — Partner products (stock and price by product id)
- Gateway: `GET https://api.apiclay.com/v1/api/gopuffapi/partner_products`
- Public headers: `Gopuff-Partner` (required), `Gopuff-Access-Token` (required)
- Public query params: `location_id` (string, required), `product_ids` (string, required)
- Upstream proxy: ApiClay proxy paid by the vendor (data cap 2 MB per call). Fetched through an ApiClay proxy paid by the vendor; a response larger than the route's data cap fails with 502 and is refunded in full.

## Call example

```bash
curl -X POST "https://api.apiclay.com/v1/api/gopuffapi/menus" \
  -H "token: <YOUR_APICLAY_TOKEN>"
```

Index of every published API: https://apiclay.com/llms.txt
