Getting started
Send your first GraphQL query with variables from cURL, JavaScript, Python or @ecomiq/core.
This guide fetches the store and the profile of seller acme in one query, with the slug passed as a variable.
Requirements
- The store's slug or one of its domains. It goes in the
x-Store-Domainheader on every request. - For the example, a marketplace store with a seller called
acme.
| Item | Value |
|---|---|
| URL | POST https:/ |
| Headers | Content-Type: application/ and x-Store-Domain: <slug-or-domain> |
| Body | { "query": "...", "variables": { ... } } |
Write the query
query SellerPage($slug: String!) {
store {
id
name
currency
}
seller(slug: $slug) {
id
name
slug
}
}$slug is String!, so the request must include it in variables:
{
"slug": "acme"
}Always pass dynamic values, such as text typed by a shopper, in variables.
Send the query
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" }
}'The response contains exactly the fields you selected, inside data:
{
"data": {
"store": {
"id": "7204558912004325301",
"name": "My store",
"currency": "PEN"
},
"seller": {
"id": "7204558912004325310",
"name": "Acme",
"slug": "acme"
}
}
}Use @ecomiq/core
createClient({ domain }) sends x-Store-Domain for you. In a theme, store(context) from @ecomiq/ already returns that client. graphql() takes the document, a Zod schema to validate data, and the variables:
import { createClient } from "@ecomiq/core";
import { z } from "zod";
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 api = createClient({ domain: "my-store" });
const data = await api.graphql(
`
query SellerPage($slug: String!) {
store { id name currency }
seller(slug: $slug) { id name slug }
}
`,
SellerPageData,
{ slug: "acme" },
);
console.log(data.store, data.seller);If the response contains errors or data doesn't match the schema, graphql() throws GraphQLResponseError.
Errors
A response with HTTP 200 can still contain errors. Check errors before you read data:
| Code | Cause |
|---|---|
BAD_USER_INPUT | An argument is invalid; for example, an empty slug or one longer than 100 characters. |
NOT_FOUND | The seller doesn't exist in the store. |
STORE_CONTEXT_REQUIRED | x-Store-Domain is missing or doesn't match a store. |
Next steps
Last updated: