Getting started
Send your first Storefront API GraphQL query with variables, fetch, or @ecomiq/storefront.
Last updated:
GraphQL is an additional method for consuming selected Storefront API reads. REST remains available for every other operation.
What you'll learn
In this guide, you'll learn how to:
- send a GraphQL document through
POST /graphql; - resolve the store with
x-Store-Domain; - keep dynamic values in
variables; - run the same query with cURL,
fetch, and@ecomiq/storefront; - validate
datawith Zod when using the SDK.
Selected reads only
The schema exposes Query, but no Mutation. Carts, checkout, customer accounts, geography, tracking, analytics, and every write operation remain in REST.
Requirements
You need the store's slug or one of its configured domains. Send that value in x-Store-Domain; it determines the data context and visibility rules.
Endpoint
| Item | Value |
|---|---|
| Method | POST |
| URL | https://storefront.ecomiq.pe/graphql |
| Content type | application/json |
| Store context | x-Store-Domain: <slug-or-domain> |
| Body | query and, when needed, variables |
IDs returned by the API are opaque. Keep them as strings and send them back without trying to construct or interpret them.
1. Write the query
This operation retrieves the store's basic context and a seller's public profile:
query SellerPage($slug: String!) {
store {
id
name
currency
}
seller(slug: $slug) {
id
name
slug
}
}$slug is declared as String!, so the operation requires a variable with that name:
{
"slug": "acme"
}Use variables for dynamic values. Do not interpolate user input into the GraphQL document.
2. Run the query with cURL
Send the document and its variables as JSON:
curl --request POST "https://storefront.ecomiq.pe/graphql" \
--header "Content-Type: application/json" \
--header "x-Store-Domain: my-store" \
--data-binary '{
"query": "query SellerPage($slug: String!) { store { id name currency } seller(slug: $slug) { id name slug } }",
"variables": { "slug": "acme" }
}'A successful execution contains the requested fields inside data:
{
"data": {
"store": {
"id": "7204558912004325301",
"name": "My store",
"currency": "PEN"
},
"seller": {
"id": "7204558912004325310",
"name": "Acme",
"slug": "acme"
}
}
}GraphQL returns only the fields included in the selection set.
3. Run the query with fetch
When you call the endpoint directly, send the store context with every request:
const query = `
query SellerPage($slug: String!) {
store { id name currency }
seller(slug: $slug) { id name slug }
}
`;
const variables = { slug: "acme" };
const response = await fetch("https://storefront.ecomiq.pe/graphql", {
method: "POST",
headers: {
"Content-Type": "application/json",
"x-Store-Domain": "my-store",
},
body: JSON.stringify({ query, variables }),
});
const result = await response.json();
if (!response.ok || result.errors?.length) {
throw new Error(result.errors?.[0]?.message ?? `HTTP ${response.status}`);
}
console.log(result.data.store, result.data.seller);A GraphQL response can include errors even with HTTP 200. See the GraphQL errors guide to handle the complete envelope.
4. Use @ecomiq/storefront
In server-side code for a store built with the SDK, createClient() reads the domain and URL from configuration. The graphql() method receives the document, a Zod schema that validates data, and optional variables:
import { createClient, z } from "@ecomiq/storefront";
const SellerPageData = z.object({
store: z.object({
id: z.string(),
name: z.string(),
currency: z.string(),
}),
seller: z.object({
id: z.string(),
name: z.string(),
slug: z.string(),
}),
});
const document = `
query SellerPage($slug: String!) {
store { id name currency }
seller(slug: $slug) { id name slug }
}
`;
const api = createClient();
const data = await api.graphql(document, SellerPageData, {
slug: "acme",
});
console.log(data.store, data.seller);The client sends POST /graphql with x-Store-Domain. If the response contains errors or data does not match the Zod schema, it throws GraphQLResponseError.