Shopify GraphQL Admin API: A Practical Guide for Developers

┌─────────────────┐       GraphQL Query        ┌────────────────────────┐
│  Your App Server│ ─────────────────────────> │ Shopify GraphQL Endpoint│
└─────────────────┘  (Single POST Request)     └────────────────────────┘
         ▲                                                 │
         │                                                 │ Evaluates Schema
         └──────────────── JSON Response ──────────────────┘ & Calculates Cost
                        (Exact Requested Fields)

https://{shop_domain}.myshopify.com/admin/api/2025-01/graphql.json

{
  "errors": "Access denied for products field. Required access scope: read_products."
}

// fetchProducts.js
const shopDomain = process.env.SHOPIFY_SHOP_DOMAIN; // e.g. "my-store.myshopify.com"
const accessToken = process.env.SHOPIFY_ACCESS_TOKEN;

const graphqlQuery = `
  query GetFirstProducts {
    products(first: 5) {
      nodes {
        id
        title
        handle
        status
        createdAt
      }
    }
  }
`;

async function fetchShopifyProducts() {
  const endpoint = `https://${shopDomain}/admin/api/2025-01/graphql.json`;

  const response = await fetch(endpoint, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Shopify-Access-Token': accessToken,
    },
    body: JSON.stringify({ query: graphqlQuery }),
  });

  if (!response.ok) {
    throw new Error(`HTTP Error: ${response.status} ${response.statusText}`);
  }

  const result = await response.json();

  if (result.errors) {
    console.error('GraphQL Errors:', result.errors);
    return;
  }

  const products = result.data.products.nodes;
  console.log(`Successfully fetched ${products.length} products:`);
  products.forEach((product) => {
    console.log(`- [${product.id}] ${product.title} (${product.handle})`);
  });
}

fetchShopifyProducts();

query GetProductsWithInventory($first: Int!) {
  products(first: $first) {
    nodes {
      id
      title
      vendor
      variants(first: 3) {
        nodes {
          id
          title
          price
          sku
          inventoryQuantity
        }
      }
    }
  }
}

mutation CreateNewProduct($input: ProductInput!) {
  productCreate(input: $input) {
    product {
      id
      title
      handle
      status
    }
    userErrors {
      field
      message
    }
  }
}

{
  "input": {
    "title": "Engineering Developer Hoodie",
    "vendor": "Yash Nandvana Specs",
    "productType": "Apparel",
    "status": "ACTIVE"
  }
}

const result = await response.json();
const { product, userErrors } = result.data.productCreate;

if (userErrors && userErrors.length > 0) {
  console.error("Mutation failed with user errors:");
  userErrors.forEach((err) => console.error(`Field '${err.field}': ${err.message}`));
  return;
}

console.log("Product created successfully with ID:", product.id);

const query = `
  query FindProductById($id: ID!) {
    product(id: $id) {
      id
      title
      descriptionHtml
    }
  }
`;

const variables = {
  id: "gid://shopify/Product/8923471928371",
};

const response = await fetch(endpoint, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Shopify-Access-Token": accessToken,
  },
  body: JSON.stringify({ query, variables }),
});

async function fetchAllShopifyProducts() {
  const endpoint = `https://${shopDomain}/admin/api/2025-01/graphql.json`;
  
  const query = `
    query GetAllProducts($first: Int!, $after: String) {
      products(first: $first, after: $after) {
        pageInfo {
          hasNextPage
          endCursor
        }
        nodes {
          id
          title
        }
      }
    }
  `;

  let hasNextPage = true;
  let cursor = null;
  const allProducts = [];

  while (hasNextPage) {
    const response = await fetch(endpoint, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-Shopify-Access-Token": accessToken,
      },
      body: JSON.stringify({
        query,
        variables: { first: 50, after: cursor },
      }),
    });

    const result = await response.json();
    const { nodes, pageInfo } = result.data.products;

    allProducts.push(...nodes);
    hasNextPage = pageInfo.hasNextPage;
    cursor = pageInfo.endCursor;

    console.log(`Fetched ${allProducts.length} total products so far...`);
  }

  return allProducts;
}

{
  "data": { ... },
  "extensions": {
    "cost": {
      "requestedQueryCost": 12,
      "actualQueryCost": 8,
      "throttleStatus": {
        "maximumAvailable": 1000.0,
        "currentlyAvailable": 992.0,
        "restoreRate": 50.0
      }
    }
  }
}

async function executeGraphQL(query, variables = {}) {
  const response = await fetch(endpoint, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Shopify-Access-Token": accessToken,
    },
    body: JSON.stringify({ query, variables }),
  });

  // Layer 1: HTTP Error Check
  if (!response.ok) {
    if (response.status === 429) {
      console.warn("Throttled by Shopify! Wait before retrying.");
    }
    throw new Error(`HTTP Error ${response.status}`);
  }

  const result = await response.json();

  // Layer 2: Top-Level GraphQL Error Check
  if (result.errors) {
    throw new Error(`GraphQL Error: ${JSON.stringify(result.errors)}`);
  }

  return result.data;
}

fragment ProductCoreDetails on Product {
  id
  title
  handle
  status
  updatedAt
}

query GetSingleProduct($id: ID!) {
  product(id: $id) {
    ...ProductCoreDetails
    descriptionHtml
  }
}

mutation CreateBulkProductExport {
  bulkOperationRunQuery(
    query: """
      {
        products {
          edges {
            node {
              id
              title
              handle
            }
          }
        }
      }
    """
  ) {
    bulkOperation {
      id
      status
    }
    userErrors {
      field
      message
    }
  }
}

┌─────────────────┐       1. Webhook Event         ┌────────────────────────┐
│  Shopify Store  │ ─────────────────────────────> │  Your Webhook Endpoint │
└─────────────────┘      (e.g. orders/create)      └────────────────────────┘
         │                                                     │
         │                                                     │ 2. Extract Order ID
         ▼                                                     ▼
┌─────────────────┐       3. Fetch Details         ┌────────────────────────┐
│ Shopify GraphQL │ <───────────────────────────── │  Service Layer Worker  │
│    Admin API    │ ─────────────────────────────> └────────────────────────┘
└─────────────────┘       4. Detailed Data                     │ 5. Persist
                                                               ▼
                                                   ┌────────────────────────┐
                                                   │        Database        │
                                                   └────────────────────────┘

┌────────────────────────┐
│  Client / Next.js UI   │
└────────────────────────┘
            │
            ▼
┌────────────────────────┐
│   Backend Service      │  • Centralized Credentials
│     (Node.js/API)      │  • Query Cost & Throttling Buffer
└────────────────────────┘  • Logging & Error Parsing
            │
            ▼
┌────────────────────────┐
│ Shopify GraphQL Engine │
└────────────────────────┘