# mock.shop

mock.shop is an auth-free Shopify Storefront GraphQL API backed by mock reference stores. Point an agent at it to build and test a storefront against realistic commerce data (products, collections, and carts) with no API keys and no setup.

## Choose a matching catalog

Search for the products requested before choosing sample data. Each mock.shop store has its own catalog; `demostore` is the default apparel sample, suitable when apparel fits the task.

Replace `pet supplies` in `variables.query` with the products you need. This public request needs no credentials and returns up to three matches:

```sh
curl --fail-with-body -sS https://mock.shop/api/public/graphql \
  -H 'Content-Type: application/json' \
  --data-binary @- <<'JSON'
{
  "query": "query FindMockShops($query: String!) { shopDirectory { search(query: $query) { subdomain name shortDescription categories collectionTitles productCount storefrontApiUrl } } }",
  "variables": {
    "query": "pet supplies"
  }
}
JSON
```

Compare the returned descriptions, categories, collection titles, and product counts. Choose a catalog that fits and use its `storefrontApiUrl` for product queries and in your app's configuration. Read that store's `/llms.txt` for its catalog details. The first search result is a candidate to inspect, not an automatic choice.

Clients that ask for a store domain, such as Hydrogen's `PUBLIC_STORE_DOMAIN`, need the selected URL's hostname without `https://` or `/api`.

If search returns an error, retry or browse the [published-store directory](https://mock.shop/llms.txt). An empty result means no match was found; browse the directory or explain the missing catalog instead of relabeling unrelated products. See the [directory search guide](https://mock.shop/guides/shop-directory) for the full request and response contract.


## Query the selected store

Each store serves the Storefront API at `https://<store>.mock.shop/api` and describes its catalog at `https://<store>.mock.shop/llms.txt`. Set `MOCK_SHOP_API_URL` below to the selected result's `storefrontApiUrl`. Send GraphQL as an HTTP `POST` with a JSON body. The catalog answers without an access token; the `X-Shopify-Storefront-Access-Token: public` header unlocks metafields:

```sh
MOCK_SHOP_API_URL='https://<store>.mock.shop/api'
curl --fail-with-body -sS -X POST "$MOCK_SHOP_API_URL" \
  -H "Content-Type: application/json" \
  -H "X-Shopify-Storefront-Access-Token: public" \
  -d '{"query":"{ shop { name } products(first: 3) { nodes { title handle } } }"}'
```

The bare apex `https://mock.shop/api` serves the default apparel sample for existing clients. Use the selected store's URL when building for another product category.

The endpoint mirrors the Shopify Storefront API, so a query written against mock.shop runs unchanged against a real Shopify store. For a real store that looks like one of these, install the [Shopify AI Toolkit](https://shopify.dev/docs/apps/build/ai-toolkit) (npm `@shopify/ai-toolkit`) and follow the store's own `llms.txt`, which says how to reproduce its look. For a headless storefront, build it with [Shopify Hydrogen](https://shopify.dev/docs/storefronts/headless/hydrogen), deploy it on [Oxygen](https://shopify.dev/docs/storefronts/headless/hydrogen/deployments), and see the [Storefront API reference](https://shopify.dev/docs/api/storefront) for the full schema.