Shopify

A Shopify store over the API an ecommerce agent actually calls: products with option-bound variants and decimal-string prices, inventory as the four quantity names across two locations, orders whose financial and fulfillment statuses are derived rather than stored, fulfillments that leave an order half-shipped, refunds that restock or do not, and returns that are requested before they are approved. A Partners development store is free, so the usual objection gets raised here more than anywhere. Here is what one cannot do: it is shared mutable state, its cost-based rate limiter cannot be driven to a chosen point on purpose, and no test can put an order into “one line item shipped and the other open, a refund past the window, one variant oversold to minus three” and find it there tomorrow. Slug: shopify

The calculated-cost bucket is state you can set

Shopify meters the GraphQL Admin API by calculated query cost rather than by request count, and every answer carries extensions.cost with a throttleStatus a well-written client paces itself off. A twin that omitted that block would break every such client; one that answered 429 instead of HTTP 200 with a THROTTLED entry would send every Shopify backoff down the wrong branch. So the bucket is container state. drain_cost_bucket puts it where you want it, and advancing the sandbox restores it a step at a time — which is the only way backoff code runs on the first query instead of never. The cost model is not invented. Shopify publishes the shape of the rule and not its sizing function, so the function was measured against Shopify’s own endpoint at every boundary. It reproduces Shopify’s numbers exactly, including the 1729 that Shopify’s own MAX_COST_EXCEEDED message quotes for the deepest legal query.

Three error channels, each carrying what Shopify puts in it

The Admin API has three, they carry different failures, and callers routinely check one:

A 401 with a string-valued {"errors": …} for authentication. Verified against a live shop, where a missing token and an unrecognised one turn out to be the same answer — and where authentication happens before the version in the path is looked at.
An errors[] array at HTTP 200 for everything the GraphQL layer refuses: a field the schema lacks, a malformed cursor, a connection argument out of range, a global id of the wrong type, a query over the cost limit, a missing access scope.
userErrors[] inside a 200 with no top-level errors for a business-rule rejection: a handle that collides, a refund over the maximum, a fulfillment for a line item already shipped.

Each refusal is in the channel Shopify uses for it, and nothing is promoted from one to another.

The schema is a pinned artefact

ShopifyAPI, Shopify’s own Python client, is a thin transport: it returns the raw response body as a string and parses nothing, so it can tell a caller nothing about shape. A twin conformed only against it could answer with any field name at all and pass. So Shopify’s Admin GraphQL schema is pinned beside the client, the twin’s modelled surface is written as SDL, and a test walks all 245 types — every field, every argument, every nullability, every argument default, every enum value — against Shopify’s own. Narrowing is incompleteness and says so through the not-modelled refusal; widening is invention and fails the build.

What it models

Area	Modelled
The shop	One store per container with constant domain, currency, timezone and plan, and one location, because inventory cannot exist without one. `shop { … }` is every integration’s first call and it answers the container’s constants with a full `extensions.cost`
Authentication	`X-Shopify-Access-Token: shpat_…` and nothing else — there is no `Authorization` header on this API. A missing token, an unrecognised one and an uninstalled app share Shopify’s one `401`, because Shopify publishes no distinction and the twin invents none
Scopes	The app’s granted access scopes as container state, with `HTTP 200`, `ACCESS_DENIED` and a `requiredAccess` naming the scope the call needed. `write_x` implies `read_x`, which is the rule the pinned SDK’s own `ApiAccess` encodes
Rate limits	Calculated query cost, measured: `2 + steps(first) × node cost` for a connection, 1 per object, 0 for scalars and enums, 10 for a mutation, with the requested cost charged before execution and the difference refunded after. `THROTTLED` at `HTTP 200`, the 1000-point single-query limit, and bucket sizes per plan
Versions	The dated version in the path, four stable versions served, and a retired one falling forward to the oldest supported — with `X-Shopify-API-Version` naming which was used, so a caller finds out
Products	`productCreate`, `productUpdate`, `productSet`, `productVariantsBulkCreate`/`Update`, options and option values, `DRAFT` by default, a handle derived from the title and uniquified — while a supplied handle that collides is refused — and `price` as a decimal string, never a float
Inventory	`available`, `committed`, `incoming` and `on_hand` per location, with `on_hand` derived so it cannot disagree with its parts. Adjust and set with Shopify’s own refusals, `changeFromQuantity` honoured as the compare-and-swap it is rather than accepted and ignored, a negative set refused while a negative quantity is reachable by directive, and an order that commits stock rather than consuming it
Customers	Create, update, addresses through `customerAddressCreate` — there is no `addresses` field on the input in this version — marketing consent per state, and a duplicate email refused with the field that collided
Orders	`draftOrderCreate` then `draftOrderComplete`, `#1001`-shaped names from the shop’s own sequence, a separate `confirmationNumber`, money as `MoneyBag` in two currencies, and `displayFinancialStatus` and `displayFulfillmentStatus` derived from the rows beneath them every time they are read — including `RESTOCKED`, which twins usually miss
Fulfillment	One fulfillment order per location with its own `status` and `requestStatus`, `fulfillmentCreate` for a subset of line items, `#1001.1` names that are not reused, tracking updated and cancelled, and an order left `PARTIALLY_FULFILLED` in one call
Refunds and returns	`refundCreate` with and without restock, the maximum still refundable in the refusal’s message, a refund refused because the order is genuinely too old, and returns that go `REQUESTED` → `OPEN` → `CLOSED` rather than opening straight away
Peripheral	Discount codes with a window and a usage limit whose status is a projection of both, metafields on five owner types with `jsonValue` parsed by the declared type — and a value that type cannot hold refused with Shopify’s own `INVALID_VALUE` rather than stored — a batch failure carrying its row, webhook subscriptions as recorded state only, and bulk operations with their poll-then-fetch lifecycle
Global ids	`gid://shopify/<Type>/<numeric>` everywhere, with the type segment load-bearing: a wrong-type id is a top-level error, a string that is not an id is a coercion error against the document, and a right-type id nothing holds is a `null` with the cost block present. All three verified
Paging	Relay connections with Shopify’s own cursor encoding, both directions — and `last` without `before` refused, which contradicts Shopify’s documentation and matches its API. A page size above 250 refused rather than clamped, and a malformed cursor a top-level error rather than an empty page
Sorting	Every `sortKey` the projection can order on, and each connection’s own default out of the pinned schema — `orders` is `PROCESSED_AT` at the root and `ID` on a customer, which are two different pages. A key that ranks against a search term or is derived from the rows beneath the record is refused by name rather than served in the default order
Arguments	Coerced the way Shopify coerces them, and a value that arrived in `variables` gets exactly the pass a literal gets — the unknown input field, the enum value, the required field and the global id are all checked on the path a caller’s SDK actually sends

Advancing the sandbox steps two things and no more, because a Shopify store has no other lifecycle: the cost bucket restores, and a bulk operation moves along CREATED → RUNNING → COMPLETED with its result URL fetchable only at the end. Orders do not self-fulfil and drafts do not expire.

Scenarios

stocked-store, partially-fulfilled, refund-window-closed, out-of-stock, throttled, narrow-scopes.

Not modelled

The REST Admin API, refused whole rather than half-built — a layer that worked for two paths and 404’d on the third would be worse than none. The OAuth install flow, app billing, session tokens and App Bridge. Webhook delivery: subscriptions are recorded and nothing is sent. The Storefront and Customer Account APIs, Checkout extensibility and Shopify Payments. Collections, markets, B2B companies, subscription contracts, gift cards, shipping profiles, carrier services, translations and Shopify Functions. Order editing, multi-location fulfillment routing, and productSet against a product that already exists. Introspection, and @skip and @include — which are the language’s own rather than Shopify’s, so the document they are written in parses here and the refusal names the directive instead of the @. The refusal is settled deliberately, and against Shopify’s own schema rather than by guesswork. A field Shopify does not have gets Shopify’s validator verbatim, undefinedField included, because that claim is true. A field Shopify has and this twin has not built gets a code Shopify never sends, because telling a caller the schema lacks a field that is right there would send them off to write a workaround for a problem that does not exist. Never a null node, and never a routing 404. The twin’s own README explains every such decision and where each number came from.

Getting Started

Concepts

Interfaces

The calculated-cost bucket is state you can set

Three error channels, each carrying what Shopify puts in it

The schema is a pinned artefact

What it models

Scenarios

Not modelled

​The calculated-cost bucket is state you can set

​Three error channels, each carrying what Shopify puts in it

​The schema is a pinned artefact

​What it models

​Scenarios

​Not modelled

The calculated-cost bucket is state you can set

Three error channels, each carrying what Shopify puts in it

The schema is a pinned artefact

What it models

Scenarios

Not modelled