admin-graphql

When to Use This Skill

Use Admin GraphQL API when you need to:

• Manage products, variants, collections, and pricing (preferred over REST for any business logic)
• Query or modify orders, fulfillments, and refunds
• Create or update customers and customer accounts
• Adjust inventory across multiple locations
• Create metafields and metaobjects for custom data
• Set up webhooks for event subscriptions
• Perform bulk operations on large datasets (1000+ records)
• Access the latest Shopify features (GraphQL-only endpoints)

GraphQL vs REST comparison:

Feature	GraphQL Admin	REST (Deprecated)
Rate Limiting	Cost-based; standard restore rate is 100 points/sec	Request bucket; standard restore rate is 2 requests/sec
Pagination	Cursor-based (Relay pattern)	Offset/limit (deprecated)
Field Selection	Precise (fetch only needed fields)	Fixed response shape (wasteful)
Batch Operations	Native bulk operations (JSONL)	Multiple sequential requests
Latest Features	Current platform features	Some newer features are GraphQL-only
Status	Required for new public apps	Legacy since October 1, 2024

---

API Endpoint & Authentication

Endpoint: https://{shop}.myshopify.com/admin/api/2026-07/graphql.json

Authentication:

const headers = {
  'Content-Type': 'application/json',
  'X-Shopify-Access-Token': process.env.SHOPIFY_ACCESS_TOKEN,
};

---

Cost-Based Rate Limiting

Shopify uses calculated query costs. The standard GraphQL Admin API restore rate is 100 points per second; Advanced, Plus, and enterprise plans have higher rates. A single query can't exceed 1,000 requested points. Read extensions.cost.throttleStatus instead of hard-coding one bucket size.

Handling throttling:

async function executeWithRetry(query, variables, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    const response = await fetch(endpoint, {
      method: 'POST',
      headers,
      body: JSON.stringify({ query, variables }),
    });

    const data = await response.json();

    if (data.errors?.some(e => e.extensions?.code === 'THROTTLED')) {
      const waitTime = Math.pow(2, attempt - 1) * 1000;
      console.log(`Throttled. Waiting ${waitTime}ms...`);
      await new Promise(resolve => setTimeout(resolve, waitTime));
      continue;
    }

    return data;
  }
  throw new Error('Max retries exceeded');
}