Collapse sidebar

GraphQL Admin API

Choose a version:

unstable 2026-10 release candidate2026-07 latest2026-04 2026-01 2025-10

Access
Analytics
Apps
B2B
Billing
Bulk operations
Cart
Checkout and accounts configurations
Checkout branding
Common objects
Customers
Discounts and marketing
Inventory
Localizations
Metafields
Metaobjects
Online store
Orders
Privacy
Products and collections
Retail
Shipping and fulfillment
Shopify Markets
Shopify Payments
Store properties
Timeline events
Webhooks
GraphQL Types

Full index

GraphQL Admin API reference

The Admin API lets you build apps and integrations that extend and enhance the Shopify admin.

This page will help you get up and running with Shopifys GraphQL API.

Install AI ToolkitAsk about this pageCopy MD

Choose a version:

unstable 2026-10 release candidate2026-07 latest2026-04 2026-01 2025-10

Anchor to Client librariesClient libraries

Use Shopifys officially supported libraries to build fast, reliable apps with the programming languages and frameworks you already know.

[]

React Router

The official package for React Router applications.

[]

Node.js

The official client library for Node.js apps. No framework dependenciesworks with any Node.js app.

[]

Ruby

The official client library for Ruby apps.

[]

cURL

Use the curl utility to make API queries directly from the command line.

Direct API Access

Make requests to the Admin API directly from your app using the standard web fetch API. Requests are automatically authenticated and fast because Shopify handles them directly.

Other

Need a different language? Check the list of community-supported libraries.

React RouterNode.jsRubycURLDirect API Access

Copy

npm install -g @shopify/cli@latest

shopify app init

npm install --save @shopify/shopify-api

# or

yarn add @shopify/shopify-api

bundle add shopify_api

# cURL is often available by default on macOS and Linux.

# See http://curl.se/docs/install.html for more details.

# Enable Direct API access in App Home.

[access.admin]

embedded_app_direct_api_access = true

React Router

npm install -g @shopify/cli@latest
shopify app init

Node.js

npm install --save @shopify/shopify-api
# or
yarn add @shopify/shopify-api

Ruby

bundle add shopify_api

cURL

# cURL is often available by default on macOS and Linux.
# See http://curl.se/docs/install.html for more details.

Direct API Access

# Enable Direct API access in App Home.
[access.admin]
embedded_app_direct_api_access = true

Anchor to AuthenticationAuthentication

Every GraphQL Admin API request carries an access token in the X-Shopify-Access-Token header. For most apps you don't fetch or set that token yourself: the Shopify CLI template and Direct API access authenticate each request for you. To set up authentication for your app type, see About app authentication. For the token types and the grants that issue them, see access tokens.

The tabs show the same request through Shopify's client libraries and as a raw HTTP call.

To keep the platform secure, apps need to request specific access scopes during the install process. Only request as much data access as your app needs to work.

Learn more about building apps.

React RouterNode.jsRubycURLDirect API Access

Copy

import { authenticate } from "../shopify.server";

export async function loader({request}) {

const { admin } = await authenticate.admin(request);

const response = await admin.graphql(

`query { shop { name } }`,

);

}

const client = new shopify.clients.Graphql({session});

const response = await client.query({data: 'query { shop { name } }'});

session = ShopifyAPI::Auth::Session.new(

shop: 'your-development-store.myshopify.com',

access_token: access_token,

)

client = ShopifyAPI::Clients::Graphql::Admin.new(

session: session,

)

response = client.query(query: 'query { shop { name } }')

# Replace {SHOPIFY_ACCESS_TOKEN} with your actual access token

curl -X POST \

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

-H 'Content-Type: application/json' \

-H 'X-Shopify-Access-Token: {SHOPIFY_ACCESS_TOKEN}' \

-d '{

"query": "query { shop { name } }"

// Authentication is handled automatically!

const response = await fetch('shopify:admin/api/2026-07/graphql.json', {

method: 'POST',

body: JSON.stringify({

query: `query { shop { name } }`,

}),

});

const { data } = await response.json();

console.log(data);

React Router

import { authenticate } from "../shopify.server";

export async function loader({request}) {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `query { shop { name } }`,
  );
}

Node.js

const client = new shopify.clients.Graphql({session});
const response = await client.query({data: 'query { shop { name } }'});

Ruby

session = ShopifyAPI::Auth::Session.new(
  shop: 'your-development-store.myshopify.com',
  access_token: access_token,
)
client = ShopifyAPI::Clients::Graphql::Admin.new(
  session: session,
)
response = client.query(query: 'query { shop { name } }')

cURL

# Replace {SHOPIFY_ACCESS_TOKEN} with your actual access token
  curl -X POST \
  https://{shop}.myshopify.com/admin/api/2026-07/graphql.json \
  -H 'Content-Type: application/json' \
  -H 'X-Shopify-Access-Token: {SHOPIFY_ACCESS_TOKEN}' \
  -d '{
  "query": "query { shop { name } }"
  }'

Direct API Access

// Authentication is handled automatically!
const response = await fetch('shopify:admin/api/2026-07/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `query { shop { name } }`,
  }),
});

const { data } = await response.json();
console.log(data);

Anchor to Endpoints and queriesEndpoints and queries

GraphQL queries are executed by sending POST HTTP requests to the endpoint:

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

Queries begin with one of the objects listed under QueryRoot. The QueryRoot is the schemas entry-point for queries.

Queries are equivalent to making a GET request in REST. The example shown is a query to get the ID and title of the first three products.

Learn more about API usage.

Note

Explore and learn Shopify's Admin API using GraphiQL Explorer. To build queries and mutations with shop data, install Shopifys GraphiQL app.

POST

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

React RouterNode.jsRubycURLDirect API Access

Copy

import { authenticate } from "../shopify.server";

export async function loader({request}) {

const { admin } = await authenticate.admin(request);

const response = await admin.graphql(

`#graphql

query getProducts {

products (first: 3) {

edges {

node {

title

}

}`,

);

const json = await response.json();

return { products: json?.data?.products?.edges };

}

const queryString = `{

products (first: 3) {

edges {

node {

title

}

// `session` is built as part of the OAuth process

const client = new shopify.clients.Graphql({session});

const products = await client.query({

data: queryString,

});

query = <<~GQL

{

products (first: 3) {

edges {

node {

title

}

GQL

# session is built as part of the OAuth process

client = ShopifyAPI::Clients::Graphql::Admin.new(

session: session

)

products = client.query(

query: query,

)

# Get the ID and title of the three most recently added products

curl -X POST https://{store_name}.myshopify.com/admin/api/2026-07/graphql.json \

-H 'Content-Type: application/json' \

-H 'X-Shopify-Access-Token: {access_token}' \

-d '{

"query": "{

products(first: 3) {

edges {

node {

title

}

const response = await fetch('shopify:admin/api/2026-07/graphql.json', {

method: 'POST',

body: JSON.stringify({

query: `{

products(first: 3) {

edges {

node {

title

}

}`,

}),

});

const { data } = await response.json();

console.log(data);

React Router

import { authenticate } from "../shopify.server";

export async function loader({request}) {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
    query getProducts {
      products (first: 3) {
        edges {
          node {
            id
            title
          }
        }
      }
    }`,
  );
  const json = await response.json();
  return { products: json?.data?.products?.edges };
}

Node.js

const queryString = `{
  products (first: 3) {
    edges {
      node {
        id
        title
      }
    }
  }
}`

// `session` is built as part of the OAuth process
const client = new shopify.clients.Graphql({session});
const products = await client.query({
  data: queryString,
});

Ruby

query = <<~GQL
  {
    products (first: 3) {
      edges {
        node {
          id
          title
        }
      }
    }
  }
GQL

# session is built as part of the OAuth process
client = ShopifyAPI::Clients::Graphql::Admin.new(
  session: session
)
products = client.query(
  query: query,
)

cURL

# Get the ID and title of the three most recently added products
curl -X POST   https://{store_name}.myshopify.com/admin/api/2026-07/graphql.json \
  -H 'Content-Type: application/json' \
  -H 'X-Shopify-Access-Token: {access_token}' \
  -d '{
  "query": "{
    products(first: 3) {
      edges {
        node {
          id
          title
        }
      }
    }
  }"
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-07/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `{
      products(first: 3) {
        edges {
          node {
            id
            title
          }
        }
      }
    }`,
  }),
});

const { data } = await response.json();
console.log(data);

Anchor to Rate limitsRate limits

The GraphQL Admin API is rate-limited using calculated query costs, measured in cost points. Each field returned by a query costs a set number of points. The total cost of a query is the maximum of possible fields selected, so more complex queries cost more to run.

Learn more about rate limits.

{}

Request

Copy

{

products(first: 1) {

edges {

node {

title

}

{}

Response

Copy

{

"data": {

"products": {

"edges": [

{

"node": {

"title": "Hiking backpack"

}

]

}

"extensions": {

"cost": {

"requestedQueryCost": 3,

"actualQueryCost": 3,

"throttleStatus": {

"maximumAvailable": 1000.0,

"currentlyAvailable": 997,

"restoreRate": 50.0

}

Anchor to Status and error codesStatus and error codes

All API queries return HTTP status codes that contain more information about the response.

Anchor to 200 OK200 OK

GraphQL HTTP status codes are different from REST API status codes. Most importantly, the GraphQL API can return a 200 OK response code in cases that would typically produce 4xx or 5xx errors in REST.

Anchor to Error handlingError handling

The response for the errors object contains additional detail to help you debug your operation.

The response for mutations contains additional detail to help debug your query. To access this, you must request userErrors.

Properties

errorsarray

A list of all errors returned

Show error item properties

errors[n].messagestring

Contains details about the error(s).

errors[n].extensionsobject

Provides more information about the error(s) including properties and metadata.

Show extensions properties

errors[n].extensions.codestring

Shows error codes common to Shopify. Additional error codes may also be shown.

Show common error codes

THROTTLED

The client has exceeded the rate limit. Similar to 429 Too Many Requests.

ACCESS_DENIED

The client doesnt have correct authentication credentials. Similar to 401 Unauthorized.

SHOP_INACTIVE

The shop is not active. This can happen when stores repeatedly exceed API rate limits or due to fraud risk.

INTERNAL_SERVER_ERROR

Shopify experienced an internal error while processing the request. This error is returned instead of 500 Internal Server Error in most circumstances.

Anchor to 4xx and 5xx status codes4xx and 5xx status codes

The 4xx and 5xx errors occur infrequently. They are often related to network communications, your account, or an issue with Shopifys services.

Many errors that would typically return a 4xx or 5xx status code, return an HTTP 200 errors response instead. Refer to the 200 OK section above for details.

{}

Sample 200 error responses

ThrottledInternal

{

"errors": [

{

"message": "Query cost is 2003, which exceeds the single query max cost limit (1000).

See https://shopify.dev/concepts/about-apis/rate-limits for more information on how the

cost of a query is calculated.

To query larger amounts of data with fewer limits, bulk operations should be used instead.

See https://shopify.dev/tutorials/perform-bulk-operations-with-admin-api for usage details.

"extensions": {

"code": "MAX_COST_EXCEEDED",

"cost": 2003,

"maxCost": 1000,

"documentation": "https://shopify.dev/api/usage/limits#rate-limits"

}

]

}

{

"errors": [

{

"message": "Internal error. Looks like something went wrong on our end.

Request ID: 1b355a21-7117-44c5-8d8b-8948082f40a8 (include this in support requests).",

"extensions": {

"code": "INTERNAL_SERVER_ERROR",

"requestId": "1b355a21-7117-44c5-8d8b-8948082f40a8"

}

]

}

Throttled

{
"errors": [
  {
    "message": "Query cost is 2003, which exceeds the single query max cost limit (1000).

See https://shopify.dev/concepts/about-apis/rate-limits for more information on how the
cost of a query is calculated.

To query larger amounts of data with fewer limits, bulk operations should be used instead.
See https://shopify.dev/tutorials/perform-bulk-operations-with-admin-api for usage details.
",
    "extensions": {
      "code": "MAX_COST_EXCEEDED",
      "cost": 2003,
      "maxCost": 1000,
      "documentation": "https://shopify.dev/api/usage/limits#rate-limits"
    }
  }
]
}

Internal

{
"errors": [
  {
    "message": "Internal error. Looks like something went wrong on our end.
Request ID: 1b355a21-7117-44c5-8d8b-8948082f40a8 (include this in support requests).",
    "extensions": {
      "code": "INTERNAL_SERVER_ERROR",
      "requestId": "1b355a21-7117-44c5-8d8b-8948082f40a8"
    }
  }
]
}

Anchor to 4xx and 5xx status codes4xx and 5xx status codes

The 4xx and 5xx errors occur infrequently. They are often related to network communications, your account, or an issue with Shopifys services.

Many errors that would typically return a 4xx or 5xx status code, return an HTTP 200 errors response instead. Refer to the 200 OK section above for details.

Anchor to [object Object]`400 Bad Request`

The server will not process the request.

Anchor to [object Object]`402 Payment Required`

The shop is frozen. The shop owner will need to pay the outstanding balance to unfreeze the shop.

Anchor to [object Object]`403 Forbidden`

The shop is forbidden. Returned if the store has been marked as fraudulent.

Anchor to [object Object]`404 Not Found`

The resource isnt available. This is often caused by querying for something thats been deleted.

Anchor to [object Object]`423 Locked`

The shop isnt available. This can happen when stores repeatedly exceed API rate limits or due to fraud risk.

Anchor to [object Object]`5xx Errors`

An internal error occurred in Shopify. Check out the Shopify status page for more information.

Info

Didnt find the status code youre looking for? View the complete list of API status response and error codes.

{}

Sample error codes

400402403404423500

HTTP/1.1 400 Bad Request

{

"errors": {

"query": "Required parameter missing or invalid"

}

HTTP/1.1 402 Payment Required

{

"errors": "This shop's plan does not have access to this feature"

}

HTTP/1.1 403 Access Denied

{

"errors": "User does not have access"

}

HTTP/1.1 404 Not Found

{

"errors": "Not Found"

}

HTTP/1.1 423 Locked

{

"errors": "This shop is unavailable"

}

HTTP/1.1 500 Internal Server Error

{

"errors": "An unexpected error occurred"

}

400

HTTP/1.1 400 Bad Request
{
  "errors": {
    "query": "Required parameter missing or invalid"
  }
}

402

HTTP/1.1 402 Payment Required
{
  "errors": "This shop's plan does not have access to this feature"
}

403

HTTP/1.1 403 Access Denied
{
  "errors": "User does not have access"
}

404

HTTP/1.1 404 Not Found
{
  "errors": "Not Found"
}

423

HTTP/1.1 423 Locked
{
  "errors": "This shop is unavailable"
}

500

HTTP/1.1 500 Internal Server Error
{
  "errors": "An unexpected error occurred"
}

GraphQL Admin API reference

Anchor to Client librariesClient libraries

React Router

Node.js

Ruby

cURL

Direct API Access

Anchor to AuthenticationAuthentication

React Router

Node.js

Ruby

cURL

Direct API Access

Anchor to Endpoints and queriesEndpoints and queries

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

React Router

Node.js

Ruby

cURL

Direct API Access

Anchor to Rate limitsRate limits

Request

Response

Anchor to Status and error codesStatus and error codes

Anchor to 200 OK200 OK

Anchor to Error handlingError handling

Properties

Anchor to 4xx and 5xx status codes4xx and 5xx status codes

Sample 200 error responses

Throttled

Internal

Anchor to 4xx and 5xx status codes4xx and 5xx status codes

Anchor to [object Object]400 Bad Request

Anchor to [object Object]402 Payment Required

Anchor to [object Object]403 Forbidden

Anchor to [object Object]404 Not Found

Anchor to [object Object]423 Locked

Anchor to [object Object]5xx Errors

Sample error codes

400

402

403

404

423

500

Updates

Business growth

Legal

Shopify

Anchor to [object Object]`400 Bad Request`

Anchor to [object Object]`402 Payment Required`

Anchor to [object Object]`403 Forbidden`

Anchor to [object Object]`404 Not Found`

Anchor to [object Object]`423 Locked`

Anchor to [object Object]`5xx Errors`