# 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.

## Building with mock.shop

Every use starts from one store, chosen as "Choose a matching catalog" below says, and the store's own `llms.txt` at `https://<store>.mock.shop/llms.txt` carries the working commands for each:

- Make a new Shopify store that copies it: `POST https://<store>.mock.shop/api/clones` makes a preview store, which needs no Shopify account, with its catalog in place ("Make a Shopify store from this shop").
- Copy its catalog into a Shopify store you already have, such as a merchant's own ("Copy this catalog into a real store").
- Install its look on a store you already have, for a store that publishes one ("Reproduce this shop's look").
- Build a custom Hydrogen storefront on its catalog, which it reads in place ("Build a Hydrogen storefront", below as well).
- Query its Storefront API directly ("Query the selected store" below).

## 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 for API and Hydrogen prototypes, not an automatic choice for every apparel store.

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.

## Build a Hydrogen storefront

For a new custom Shopify storefront, use the [mock.shop Hydrogen starter](https://github.com/Shopify/mock-shop-starter). Honor an explicit framework or theme choice. It includes product routes, collections, and a cart backed by the Storefront API. No Shopify account or API token is needed to prototype with a mock.shop catalog. Use Node.js 22 or 24:

```sh
git clone https://github.com/Shopify/mock-shop-starter.git my-store
cd my-store
cp .env.example .env
```

Set `PUBLIC_STORE_DOMAIN` in `.env` to the selected catalog's hostname, without `https://` or `/api`; replace `<store>` below with your selection:

```dotenv
PUBLIC_STORE_DOMAIN=<store>.mock.shop
```

Leave Storefront API tokens unset for `*.mock.shop`.
The starter's source is available immediately after cloning. Configure the catalog and customize its routes and components while keeping its Hydrogen context, Storefront API queries, and cart. Then install dependencies and start the app:

```sh
npm install
npm run dev
```

Restart the command after changing `.env`. `@shopify/hydrogen-react` components alone do not provide the full Hydrogen app. See the [Hydrogen build guide](https://mock.shop/guides/hydrogen) for the complete flow and moving to a real store.


## 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 custom storefront, continue 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. For a Shopify store made from one of these stores with `POST https://<store>.mock.shop/api/clones`, as its `llms.txt` describes under "Make a Shopify store from this shop", the [Shopify AI Toolkit](https://shopify.dev/docs/apps/build/ai-toolkit) (npm `@shopify/ai-toolkit`) is the way to keep working on it.