Shopify simulator

shopify-twin is a local, stateful simulator of Shopify’s two GraphQL APIs, for testing code that reads and writes a store. The Admin API at /admin/api/2026-10/graphql.json serves the catalog, customers, orders, fulfillment, inventory, custom data and Online Store content. The Storefront API at /api/2026-10/graphql.json serves what a shopper sees and their carts.

The store behaves as Shopify’s does, except where a line says Differs from Shopify or Limitations lists a known issue. “Unconfirmed” marks store behavior not yet checked against a live Shopify store. The simulator never calls Shopify, takes no payment, sends no email and accepts any placeholder access token.

Quickstart

Install the CLI, sign in and boot the simulator with RYSTIC_URL pointing at it.

On Pro you sign in with an API key from your account .

curl -fsSL https://www.rystic.ai/install.sh | sh
rystic login rys_…   # your API key
export RYSTIC_URL=$(rystic run shopify-twin -d --port 0 --scenario shopify_apparel_storefront --json | jq -r .data.url)
curl -s "$RYSTIC_URL/_rystic/version"
# -> {..."product":"shopify-twin"...}

On Enterprise, the licensed edition signs in with a license file in place of the key: rystic login ./rystic-license.json (licensing ).

First calls

The default scenario is a lived-in apparel store. Read its first product on the Admin API, create a page there and read the page back on the Storefront API:

ADMIN="$RYSTIC_URL/admin/api/2026-10/graphql.json"
STOREFRONT="$RYSTIC_URL/api/2026-10/graphql.json"
curl -s "$ADMIN" -H "X-Shopify-Access-Token: shpat_placeholder" -H "Content-Type: application/json" -d '{"query": "{ products(first: 1) { nodes { id title } } }"}' | jq -c '.data.products.nodes[0]'
# -> {"id":"gid://shopify/Product/1030","title":"Cedar Rain Shell"}
curl -s "$ADMIN" -H "X-Shopify-Access-Token: shpat_placeholder" -H "Content-Type: application/json" -d '{"query": "mutation($page: PageCreateInput!) { pageCreate(page: $page) { page { id handle } userErrors { message } } }", "variables": {"page": {"title": "Shipping", "body": "<p>Free over 50</p>", "isPublished": true}}}' | jq -c '.data.pageCreate.page'
# -> {"handle":"shipping","id":"gid://shopify/Page/1"}
curl -s "$STOREFRONT" -H "X-Shopify-Storefront-Access-Token: placeholder" -H "Content-Type: application/json" -d '{"query": "{ pageByHandle(handle: \"shipping\") { id title } }"}' | jq -c '.data.pageByHandle'
# -> {"id":"gid://shopify/Page/1","title":"Shipping"}

Connect your client

A client that takes a base URL points it at $RYSTIC_URL. The official libraries pin the store’s own https://<shop>.myshopify.com host and offer no base URL. For them, boot the simulator with rystic run shopify-twin -d --port 0 --intercept and start your program as rystic exec -- <command>, which routes every *.myshopify.com host to it. Any shop name works, and the access token is a placeholder. JavaScript:

import { createAdminApiClient } from "@shopify/admin-api-client";

const client = createAdminApiClient({
  storeDomain: "example.myshopify.com",
  apiVersion: "2026-10",
  accessToken: "shpat_placeholder",
});
const { data } = await client.request("{ shop { name currencyCode } }");

Python:

import json

import shopify

session = shopify.Session("example.myshopify.com", "2026-10", "shpat_placeholder")
shopify.ShopifyResource.activate_session(session)
result = json.loads(shopify.GraphQL().execute("{ shop { name currencyCode } }"))

Go:

import (
	"context"

	goshopify "github.com/bold-commerce/go-shopify/v4"
)

func main() {
	client, _ := goshopify.NewClient(goshopify.App{}, "example.myshopify.com", "shpat_placeholder", goshopify.WithVersion("2026-10"))
	var resp struct {
		Shop struct {
			Name string `json:"name"`
		} `json:"shop"`
	}
	client.GraphQL.Query(context.Background(), "{ shop { name } }", nil, &resp)
}

Pin 2026-10 in every client: the simulator serves no other version. A Storefront client sends its token as X-Shopify-Storefront-Access-Token and reaches the same host.

Each client’s quickstart was run against this simulator in each way it connects, with the vendor’s own hosts blocked.

Auth

The Admin API takes its token in X-Shopify-Access-Token and the Storefront API in X-Shopify-Storefront-Access-Token or Shopify-Storefront-Private-Token; the simulator checks that a token is present and never its value, so any placeholder works.

An Admin request with no token, an empty one or only an Authorization: Bearer header is refused before the query is read with 401 and {"errors": "[API] Invalid API key or access token (unrecognized login or wrong password)"}, a string as in Shopify, beside WWW-Authenticate: Basic Realm="Shopify API Authentication". A Storefront token on the Admin route counts as none.

A Storefront request with no token, or with the Admin header only, returns 400 with one error, as a store whose storefront is not open does. The error’s code is BAD_REQUEST and its message Online Store channel is locked.

Which orders an Admin token can read depends on the grants bound to it (Order history window).

API version

The simulator serves Shopify API version 2026-10, on both surfaces: POST /admin/api/2026-10/graphql.json and POST /api/2026-10/graphql.json.

A caller pins the version in the path, which every Shopify library does from its apiVersion setting. Any other version, unstable included, returns 404 {"message": "No route in twin for POST /admin/api/2025-01/graphql.json"}, and so does every other path and method: the REST Admin API is not served.

Errors and limits

Error format

Both routes take a JSON body, {"query": …, "variables": …}. A refusal returns an errors array, and what each entry carries depends on the error:

A mutation refuses bad input as data: its payload’s userErrors lists each problem beside a null record. Not every payload’s error type has a code, and selecting code where it has none fails the whole query with undefinedField:

Rate limits

An Admin API response carries its cost in extensions.cost, with requestedQueryCost, actualQueryCost and a throttleStatus. The cost figures and the bucket differ from Shopify’s, and no Admin or Storefront request is ever throttled (Limitations).

Network profiles refuse a share of requests on a route with the status and body you give them, so a test can send the THROTTLED error Shopify returns.

Pagination

An Admin connection such as orders pages forward with first and after, or backward with last and before. It returns nodes, and edges with a cursor on each. Its pageInfo holds hasNextPage, hasPreviousPage, startCursor and endCursor. Treat a cursor as opaque; passing an Admin cursor this simulator never handed out is refused with a GraphQL error (unconfirmed).

first or last above a connection’s cap, or a connection given neither, returns an error (Error format). The cap is 250 on most connections. The Admin API’s productTags takes up to 5000, and productTypes, productVendors and customerSegmentMembers up to 1000. A bulk query needs neither.

Idempotency

The Admin API’s inventory writes take Shopify’s @idempotent(key:) directive: inventorySetQuantities, inventoryAdjustQuantities, inventoryMoveQuantities and inventoryActivate. The simulator accepts the directive on any field and ignores its key, so a retry with the same key applies the write again (Limitations). A pageCreate sent twice with one key makes two pages.

Coverage

The simulator covers the Admin API’s reads of a store’s catalog, customers, orders, fulfillment, inventory, custom data and content. Its Admin writes cover products (variants, options and media included), collections, inventory, publishing, pages, blogs, articles, menus, URL redirects and bulk operations. On the Storefront API it covers the catalog, content and cart operations. Order, customer and discount writes, payments, checkout, webhooks and introspection are out of scope, and so is the Customer Account API. GET /_rystic/routes lists the two routes a running simulator serves, and the table below names each GraphQL field.

On 2026-11-06, the simulator matched Shopify on 255 of the 275 tests that compare the two (92.7%), and 4 of them gave no verdict.

2 routes, counted from the simulator’s route table.

Scenarios

The simulator ships 5 scenarios; the quickstart boots shopify_apparel_storefront.

What each scenario holds:

• shopify_custom_data_lab: Three metafield definitions across three owner types, two metaobject definitions beside the standard one with three metaobjects between them, two saved segments, two customers and one abandoned checkout, plus a journal blog with one article, one published page and one curated collection published to one sales channel.
• shopify_fresh_store: Shop settings still flagged setup-required and a single primary location holding no inventory, with nothing else but the records every new store holds, so a first write’s effect on an otherwise bare store is unmistakable.

Boot one by name, or load one into a running simulator:

rystic run shopify-twin -d --port 0 --scenario shopify_apparel_storefront
curl -s -X POST "$RYSTIC_URL/_rystic/scenario" -d '{"name":"shopify_apparel_storefront"}'

What the scenarios do not hold

• No scenario holds a webhook subscription, a discount, a payment or a theme: Shopify’s operations for them are not served.
• Without --scenario, the simulator boots a store named Shop 1 holding only what a new Shopify store starts with. That is the three publications (Online Store, Shop and Point of Sale), one primary location, the frontpage collection (“Home page”) and the metaobject definition shopify--knowledge-base-fact. POST /_rystic/reset returns to it.
• Only shopify_apparel_storefront and shopify_inventory_ledger hold a cart; create one with cartCreate in the others.

Seeding state

Each Shopify resource is one register, named state_<resource> (state_customer, state_product, state_cart_line and so on), holding records keyed by their global id. Seed a customer into the running simulator and read it back on the Admin API:

curl -s -X POST "$RYSTIC_URL/_rystic/seed" -d '{"state_customer": {"gid://shopify/Customer/9001": {"id": "gid://shopify/Customer/9001", "email": "dev@example.com", "displayName": "Dev Tester"}}}'
curl -s "$ADMIN" -H "X-Shopify-Access-Token: shpat_placeholder" -H "Content-Type: application/json" -d '{"query": "{ customer(id: \"gid://shopify/Customer/9001\") { id email displayName } }"}' | jq -c '.data.customer | {id, email, displayName}'
# -> {"id":"gid://shopify/Customer/9001","email":"dev@example.com","displayName":"Dev Tester"}

A record needs only the fields you read back: one you leave out reads as empty or null.

Scenarios and seeding covers the seed response, refusals and boot files.

Features

Each feature has its own page:

• Order history window: An Admin token without the read_all_orders grant sees only orders from the last 60 days of the simulator’s clock, as in Shopify; bind grants to a token to widen it.
• Storefront carts: A shopper’s cart on the Storefront API: create it, add and change lines, set a note, attributes, buyer and discount codes, and read it back by its id.

Determinism and reset

The ids the simulator makes are sequences per resource that restart on reset: the first page you create is gid://shopify/Page/1, the first cart gid://shopify/Cart/c000000000001?key=00000001. Records a scenario seeds keep their own ids.

The clock moves one millisecond for each API request, and a createdAt the simulator stamps is the clock’s time to the second. Moving the clock changes:

• which orders a token can read, as an order ages out of its 60-day window (Order history window).

Reset and determinism covers reset, the clock and the RNG.

Limitations

Known issues.

• The simulator does not serve __schema introspection: {__schema{queryType{name}}} returns an undefinedField error where Shopify returns QueryRoot, so GraphQL codegen tools that introspect first fail.
• Fields the Shopify schema declares non-null can come back null from the simulator and null the whole data. On the Admin API they include Refund.totalRefundedSet and the Order fields currentTotalWeight, statusPageUrl and totalCashRoundingAdjustment. On the Storefront API they include Product.compareAtPriceRange and a variant’s weightUnit.
• The simulator serves the Admin API at version 2026-10 only, and serves neither POST /admin/api/unstable/graphql.json nor the Admin API’s publicApiVersions and themes queries. So the Shopify CLI’s shopify theme commands fail at their first call, which reads the version list from the unstable endpoint. Workaround: Call the simulator through @shopify/admin-api-client, @shopify/shopify-api or another Admin API client pinned to version 2026-10. Such a client sends each query to the endpoint the simulator serves. Theme reads and theme file uploads have no workaround.
• extensions.cost on the simulator does not follow Shopify’s cost rules: nested connections add nothing, and requested and actual costs can disagree. locationsCount and segment report a bucket of 1000 restoring 50, where Shopify reports 2000 and 100. customer and inventoryItem carry no cost when they find their record, metafieldDefinition and productOptionUpdate carry none, and the bucket never drains.
• node(id:) and nodes(ids:) do not resolve every stored type that implements Node: node(id:"gid://shopify/Product/1030") returns null while product(id:) returns the product.
• A relative date in a query: search, such as created_at:>-7d, returns a BAD_REQUEST error naming the field on Shopify. On the simulator it matches no record on the lists and counts that search dates, and customersCount counts every customer. The lists are orders, products, customers, productVariants, collections and inventoryItems.
• Some Admin query: searches differ from Shopify. A documented field the simulator does not search, such as fulfillment_status or id, matches every record with an invalid_field warning. A tag prefix (tag:abc*) matches where Shopify matches none. A bare word on orders searches only the order name, and a bare date matches one instant rather than the day. A malformed term on products (an unclosed ( or ", or an empty vendor:) matches nothing where Shopify still returns products. collectionsCount, customersCount and productVariantsCount ignore query: and return no extensions.search warning.
• urlRedirectCreate accepts a path another redirect already uses, where Shopify returns a CREATE_FAILED user error “Path has already been taken”.
• Storefront locations lists every location, where Shopify lists only locations that offer in-store pickup.
• A cart’s lines and a sitemap’s items fail to resolve their concrete type on the Storefront API, where Shopify returns CartLine and SitemapResource values. Selecting Cart.lines nulls the whole cart, so no cart id comes back. Sitemap items return an error.
• Storefront cart(id:) with a cart’s bare id, without the ?key= suffix, returns data.cart: null from the simulator, where Shopify returns the cart.
• An asynchronous productSet (synchronous: false) returns its operation COMPLETE at once, with the product filled in. Shopify returns it CREATED with product: null and finishes in the background.
• A product’s totalInventory and hasOutOfStockVariants keep their create-time values on the simulator: inventorySetQuantities, inventoryAdjustQuantities and inventoryMoveQuantities do not update them, where Shopify follows the variants’ inventory levels.
• Some product, collection, media and inventory item writes accept unknown ids and invalid input that Shopify refuses, and inventoryItemUpdate creates an unknown item. Catalog input is not normalized: tags are not sorted and deduplicated, description does not follow descriptionHtml and a duplicate handle gets no -1 suffix. The default collection sortOrder is not MOST_RELEVANT, and inventoryItem.sku does not follow the variant’s sku.
• A Storefront products(query:) date term with a bare year, such as created_at:>2030, matches no product on the simulator, where Shopify ignores the term and returns every product.
• The simulator ignores the @idempotent directive on inventory writes. A write without it is applied, where Shopify refuses it with a BAD_REQUEST error. A retry with the same key applies the write again, where Shopify returns the first result. On the three quantity writes, a key reused with other input is applied, where Shopify refuses it with IDEMPOTENCY_KEY_PARAMETER_MISMATCH.
• No write stores a product metafield: productCreate, productUpdate and productSet accept a metafields input and drop it without a user error. A product’s metafield comes back null and its metafields empty. Test metafield logic against a real Shopify store.
• On the Storefront API, collection, collectionByHandle and collections list a member product that is a draft or not published to the Online Store, which Shopify hides.

Beyond the known issues, 773 of the 905 operations in the published spec are not served, 5 GraphQL types may leave out non-null fields, 27 documented responses have no test yet and 220 behaviors are not modeled. The details follow.

By design.

• One store per process. One simulator holds one store whatever shop name a request carries; run one per port for isolated tests in parallel.
• No Shopify side effects. A mutation changes the simulator’s own state and nothing else: it sends no email, payment, webhook or app callback.

Release notes: Changelog