Skip to content

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-Domain header on every request.
  • For the example, a marketplace store with a seller called acme.
ItemValue
URLPOST https://storefront.ecomiq.pe/graphql
HeadersContent-Type: application/json and x-Store-Domain: <slug-or-domain>
Body{ "query": "...", "variables": { ... } }

Write the query

SellerPage.graphql
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:

Variables
{
  "slug": "acme"
}

Always pass dynamic values, such as text typed by a shopper, in variables.

Send the query

Terminal
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:

Response
{
  "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/storefront already returns that client. graphql() takes the document, a Zod schema to validate data, and the variables:

seller-page.ts
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:

CodeCause
BAD_USER_INPUTAn argument is invalid; for example, an empty slug or one longer than 100 characters.
NOT_FOUNDThe seller doesn't exist in the store.
STORE_CONTEXT_REQUIREDx-Store-Domain is missing or doesn't match a store.

Next steps

Last updated:

On this page