---
title: How to use mock.shop
description: >-
  Build and test a Shopify Storefront API integration or a Hydrogen storefront
  against realistic example data, without a Shopify store or an access token.
source_url:
  html: 'https://shopify.dev/docs/storefronts/headless/mock-shop'
  md: 'https://shopify.dev/docs/storefronts/headless/mock-shop.md'
api_name: storefront
---

# How to use mock.​shop

[mock.shop](https://mock.shop/?utm_source=docs) is a public Shopify Storefront API that serves fictional stores. It needs no store, no app, and no access token, so you or your AI coding agent can build a storefront against realistic products, collections, and carts, then switch to a real store when you're ready.

***

## How it works

Every mock.shop store is a separate catalog on its own host, and each host serves the same Storefront API at `/api`:

1. Read the store directory at [https://mock.shop/llms.txt](https://mock.shop/llms.txt?utm_source=docs). It describes every store on one line: its name, a summary of what it sells, its product categories, and its API URL.
2. Pick the store with categories that match what you're building. There are more than 100, from apparel to home decor to electronics. When nothing fits, use the default store at `https://mock.shop/api`: hoodies, t-shirts, sweatpants, and slides, organized into Tops, Bottoms, Shoes, and Accessories.
3. Send Storefront API queries as `POST` requests with a JSON body to `https://<store>.mock.shop/api`. The only header you need is `Content-Type: application/json`.
4. Read `https://<store>.mock.shop/llms.txt` for that store's product categories, collections, and product counts.

Two lines from the directory show what you're choosing from:

## https://mock.shop/llms.txt

```text
- [Elysian Thread](https://apparel.mock.shop/api): Curated timeless apparel featuring natural fabrics and clean tailoring for the modern woman's sophisticated wardrobe. Categories: Blouses, Loungewear Sets, Outfit Sets, Trousers, Cardigans, Blazers, Clothing Tops, Coats & Jackets.
- [Evergreen Echoes](https://3dpinecones.mock.shop/api): We craft exquisite, 3D-printed pinecones that capture the timeless beauty of nature for your home decor. Categories: Candle Holders, Garden Sculptures, Potpourri, Seasonal & Holiday Decorations, Window Valances & Cornices, Wreaths & Garlands, Artificial Flora, Artwork.
```

Once you've picked a store, query it the way you'd query any Storefront API. mock.shop mirrors the Storefront API, so a query written against it runs unchanged against a real store:

## Terminal

```text
curl -X POST "https://mock.shop/api?utm_source=docs" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ shop { name } products(first: 3) { nodes { title handle } } }"}'
```

## Response

```json
{
  "data": {
    "shop": {
      "name": "Mock.shop"
    },
    "products": {
      "nodes": [
        {
          "title": "Slides",
          "handle": "slides"
        },
        {
          "title": "Sweatpants",
          "handle": "sweatpants"
        },
        {
          "title": "Men's T-shirt",
          "handle": "men-t-shirt"
        }
      ]
    }
  },
  "extensions": {
    "cost": {
      "requestedQueryCost": 4
    }
  }
}
```

An agent can start from `https://mock.shop` itself. The root returns these instructions as markdown, and every `/api` response carries a `Link` header that points at the store's `llms.txt`, so an agent that starts from an API call finds the directory too.

### Limitations

mock.shop is for building, not for selling:

* Its catalogs, prices, and inventory are fictional.
* Cart operations work, so you can build the full shopping flow, but checkout is mocked: no payment is taken and no order is placed.
* It doesn't support the [Customer Account API](https://shopify.dev/docs/api/customer).

***

## Developer tools and resources

[Store directory\
\
](https://mock.shop/llms.txt?utm_source=docs)

[Every published mock.shop store, what it sells, and its API URL.](https://mock.shop/llms.txt?utm_source=docs)

[mock.shop starter\
\
](https://github.com/Shopify/mock-shop-starter)

[A Hydrogen storefront pre-configured for mock.shop, with a directory of every store, agent instructions, and a sandbox that runs in the browser.](https://github.com/Shopify/mock-shop-starter)

[GraphQL Storefront API reference\
\
](https://shopify.dev/docs/api/storefront)

[The queries and mutations that mock.shop answers.](https://shopify.dev/docs/api/storefront)

[Hydrogen\
\
](https://shopify.dev/docs/storefronts/headless/hydrogen/getting-started)

[Shopify's storefront framework. New projects scaffold against mock.shop data with one flag.](https://shopify.dev/docs/storefronts/headless/hydrogen/getting-started)

***

## Get started

### Scaffold a new project

Scaffold a Hydrogen storefront that reads mock.shop data:

## Terminal

```text
npm create @shopify/hydrogen@latest -- --mock-shop
```

The `--quickstart` flag in the Hydrogen getting-started guide includes `--mock-shop`.

### Start from the mock.​shop starter

The [mock.shop starter](https://github.com/Shopify/mock-shop-starter) on GitHub is the same Hydrogen skeleton, pre-configured for mock.shop and published as a template repository. It adds:

* A directory of every mock.shop store.
* Agent instructions in `AGENTS.md` and `llms.txt`, and a Cursor rule.
* A link to a sandbox that runs the storefront in your browser with nothing installed.

To run it locally:

## Terminal

```text
git clone https://github.com/Shopify/mock-shop-starter.git my-store
cd my-store
cp .env.example .env
npm install
npm run dev
```

### Point an existing project at mock.​shop

Set `PUBLIC_STORE_DOMAIN` to a store host (such as `snowboards.mock.shop`) and leave the Storefront API token empty.

Hydrogen's storefront client recognizes any mock.shop host and sends no token. Other Storefront API clients work the same way: they need only the store domain. The standard versioned endpoint, such as `https://<store>.mock.shop/api/2026-07/graphql.json`, serves the same schema at every version.

### Move to a real store

When you're ready to use a real store, link the project with `npx shopify hydrogen link` and pull its credentials with `npx shopify hydrogen env pull`. Other clients switch by changing the store domain and adding the store's access token.

[Getting started with Hydrogen and Oxygen\
\
](https://shopify.dev/docs/storefronts/headless/hydrogen/getting-started)

[Create a Hydrogen storefront with mock.shop data, link it to your store, and deploy it to Oxygen.](https://shopify.dev/docs/storefronts/headless/hydrogen/getting-started)

***