### Install Shopify CLI and Initialize React Router App

Source: https://shopify.dev/docs/api/admin-graphql/latest

Install the latest Shopify CLI globally and initialize a new Shopify app using the React Router template. This sets up the foundational project structure for building Shopify admin apps.

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

--------------------------------

### Client Library Installation

Source: https://shopify.dev/docs/api/admin-graphql/latest

Install Shopify's officially supported client libraries for various programming languages and frameworks. Choose the library that matches your development environment to build fast and reliable Shopify apps.

```APIDOC
## Client Libraries Installation

### Description
Shopify provides officially supported client libraries for multiple programming languages and frameworks to simplify GraphQL API integration.

### Available Libraries

#### React Router
The official package for React Router applications.
- **Installation**: `npm install -g @shopify/cli@latest && shopify app init`
- **Resources**: Docs, npm package, GitHub repo

#### Node.js
The official client library for Node.js apps with no framework dependencies.
- **Installation**: `npm install --save @shopify/shopify-api` or `yarn add @shopify/shopify-api`
- **Resources**: Docs, npm package, GitHub repo

#### Ruby
The official client library for Ruby applications.
- **Installation**: `bundle add shopify_api`
- **Resources**: Docs, Ruby gem, GitHub repo

#### cURL
Use the curl utility to make API queries directly from the command line.
- **Availability**: Often available by default on macOS and Linux
- **Installation Guide**: http://curl.se/docs/install.html

### Installation Examples

#### 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.
```
```

--------------------------------

### Install Shopify GraphQL API Client - Node.js

Source: https://shopify.dev/docs/api/admin-graphql/latest

Add the official Shopify GraphQL API client library to a Node.js project using npm or yarn. This library provides no framework dependencies and works with any Node.js application.

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

--------------------------------

### Install Shopify API Gem - Ruby

Source: https://shopify.dev/docs/api/admin-graphql/latest

Add the official Shopify API gem to a Ruby project using Bundler. This provides the GraphQL client library for Ruby applications.

```bash
bundle add shopify_api
```

--------------------------------

### Query Products with GraphQL - React Router

Source: https://shopify.dev/docs/api/admin-graphql/latest

Executes a GraphQL query to fetch the first three products with their ID and title using React Router loader and Shopify's authenticate.admin method. Requires prior authentication setup and returns product edges data.

```javascript
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 };
}
```

--------------------------------

### POST /admin/api/{version}/graphql.json

Source: https://shopify.dev/docs/api/admin-graphql/latest

Executes a GraphQL query against the Shopify Admin API to retrieve data. This example demonstrates fetching the ID and title of the first three products. Requests typically require 'Content-Type: application/json' and 'X-Shopify-Access-Token' headers.

```APIDOC
## POST /admin/api/{version}/graphql.json

### Description
Executes a GraphQL query against the Shopify Admin API to retrieve data. This example demonstrates fetching the ID and title of the first three products. Requests typically require 'Content-Type: application/json' and 'X-Shopify-Access-Token' headers.

### Method
POST

### Endpoint
https://{store_name}.myshopify.com/admin/api/{version}/graphql.json

### Parameters
#### Path Parameters
- **store_name** (string) - Required - The name of the Shopify store.
- **version** (string) - Required - The API version, e.g., `2026-01`.

#### Query Parameters
(None directly for the HTTP endpoint; GraphQL queries define their own parameters within the request body.)

#### Request Body
- **query** (string) - Required - The GraphQL query string to be executed.

### Request Example
```json
{
  "query": "{\n    products(first: 3) {\n      edges {\n        node {\n          id\n          title\n        }\n      }\n    }\n  }"
}
```

### Response
#### Success Response (200)
- **data** (object) - The data returned by the GraphQL query.
- **errors** (array) - Optional - An array of error objects if the GraphQL operation encountered issues, even with a 200 HTTP status.

#### Response Example
```json
{
  "data": {
    "products": {
      "edges": [
        {
          "node": {
            "id": "gid://shopify/Product/12345",
            "title": "Example Product 1"
          }
        },
        {
          "node": {
            "id": "gid://shopify/Product/67890",
            "title": "Example Product 2"
          }
        },
        {
          "node": {
            "id": "gid://shopify/Product/11223",
            "title": "Example Product 3"
          }
        }
      ]
    }
  },
  "errors": []
}
```
```

--------------------------------

### Handle HTTP 404 Not Found Error Response (Shopify Admin GraphQL)

Source: https://shopify.dev/docs/api/admin-graphql/latest

This snippet provides an example of an HTTP 404 Not Found error response, signifying that the requested resource could not be located on the server. The JSON response includes a simple 'Not Found' message.

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

--------------------------------

### Query GraphQL Admin API - Ruby

Source: https://shopify.dev/docs/api/admin-graphql/latest

Initialize a ShopifyAPI session with shop credentials and access token, then create a GraphQL admin client to execute queries. Returns shop information from the API.

```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 } }')
```

--------------------------------

### Query Products with GraphQL - Ruby

Source: https://shopify.dev/docs/api/admin-graphql/latest

Executes a GraphQL query to fetch the first three products using Shopify's Ruby API client. Requires an authenticated session and uses heredoc syntax for query definition.

```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,
)
```

--------------------------------

### Query Products with GraphQL - Node.js

Source: https://shopify.dev/docs/api/admin-graphql/latest

Executes a GraphQL query to retrieve the first three products using Shopify's Node.js client library. Requires an authenticated session object and returns product data from the query response.

```javascript
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,
});
```

--------------------------------

### Query Products with GraphQL - cURL

Source: https://shopify.dev/docs/api/admin-graphql/latest

Executes a GraphQL query via HTTP POST request to fetch the first three products. Requires valid store name and access token in headers, with query payload in JSON format.

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

--------------------------------

### Query GraphQL Admin API - Node.js

Source: https://shopify.dev/docs/api/admin-graphql/latest

Create a GraphQL client instance with a session and execute a query to retrieve shop information. The client handles authentication and request formatting.

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

--------------------------------

### Error Response - 403 Access Denied

Source: https://shopify.dev/docs/api/admin-graphql/latest

Returned when the authenticated user does not have the required permissions to access the requested resource or perform the requested action.

```APIDOC
## Error Response - 403 Access Denied

### Description
Returned when the authenticated user does not have the required permissions to access the requested resource.

### HTTP Status Code
403 Access Denied

### Error Response
```json
{
  "errors": "User does not have access"
}
```

### Possible Causes
- User lacks required OAuth scopes
- User role does not have permission for this operation
- API credentials have insufficient privileges
```

--------------------------------

### Error Response - 404 Not Found

Source: https://shopify.dev/docs/api/admin-graphql/latest

Returned when the requested resource does not exist or cannot be found. This error indicates that the endpoint or resource identifier is invalid or the resource has been deleted.

```APIDOC
## Error Response - 404 Not Found

### Description
Returned when the requested resource does not exist or cannot be found.

### HTTP Status Code
404 Not Found

### Error Response
```json
{
  "errors": "Not Found"
}
```

### Possible Causes
- Invalid resource ID or identifier
- Resource has been deleted
- Incorrect endpoint path
```

--------------------------------

### Handle HTTP 403 Access Denied Error Response (Shopify Admin GraphQL)

Source: https://shopify.dev/docs/api/admin-graphql/latest

This snippet shows an HTTP 403 Access Denied error response, indicating that the authenticated user lacks the necessary permissions to perform the requested action. The JSON response contains a general message about the user's access limitations.

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

--------------------------------

### Query GraphQL Admin API - cURL

Source: https://shopify.dev/docs/api/admin-graphql/latest

Make a direct HTTP POST request to the Shopify GraphQL Admin API endpoint using cURL. Requires a valid access token in the X-Shopify-Access-Token header and shop domain.

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

--------------------------------

### Error Response - 402 Payment Required

Source: https://shopify.dev/docs/api/admin-graphql/latest

Returned when the shop's current plan does not have access to the requested feature. This indicates a subscription or billing limitation that prevents access to the API endpoint.

```APIDOC
## Error Response - 402 Payment Required

### Description
Returned when the shop's current plan does not have access to the requested feature.

### HTTP Status Code
402 Payment Required

### Error Response
```json
{
  "errors": "This shop's plan does not have access to this feature"
}
```

### Possible Causes
- Shop subscription plan lacks required feature access
- Feature requires a higher tier plan
- Billing account is not in good standing
```

--------------------------------

### Handle HTTP 402 Payment Required Error Response (Shopify Admin GraphQL)

Source: https://shopify.dev/docs/api/admin-graphql/latest

This snippet demonstrates an HTTP 402 Payment Required error response, indicating that the shop's current plan does not grant access to the requested feature. The JSON response provides a concise error message explaining the access limitation.

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

--------------------------------

### Error Response - 423 Locked

Source: https://shopify.dev/docs/api/admin-graphql/latest

Returned when the shop is temporarily unavailable or locked. This indicates that the shop cannot process requests at this time due to maintenance, suspension, or other operational issues.

```APIDOC
## Error Response - 423 Locked

### Description
Returned when the shop is temporarily unavailable or locked.

### HTTP Status Code
423 Locked

### Error Response
```json
{
  "errors": "This shop is unavailable"
}
```

### Possible Causes
- Shop is under maintenance
- Shop account has been suspended
- Shop is temporarily locked for security reasons
- Retry the request after a short delay
```

--------------------------------

### Handle HTTP 400 Bad Request Error Response (Shopify Admin GraphQL)

Source: https://shopify.dev/docs/api/admin-graphql/latest

This snippet illustrates an HTTP 400 Bad Request error response, indicating that the server could not understand the request due to invalid or missing parameters. It shows the typical JSON structure returned by the Shopify Admin GraphQL API for such an error, detailing the specific query parameter issue.

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

--------------------------------

### GraphQL Admin API Authentication

Source: https://shopify.dev/docs/api/admin-graphql/latest

All GraphQL Admin API requests require a valid Shopify access token. Learn how to authenticate requests using the X-Shopify-Access-Token header and implement authentication across different client libraries and frameworks.

```APIDOC
## POST /admin/api/{version}/graphql.json

### Description
Authenticate and execute GraphQL queries against the Shopify Admin API. All requests require a valid access token passed via the X-Shopify-Access-Token header or through authenticated client libraries.

### Method
POST

### Endpoint
`https://{shop}.myshopify.com/admin/api/{version}/graphql.json`

### Authentication
- **Access Token**: Required - Valid Shopify access token from OAuth or custom app
- **Header**: `X-Shopify-Access-Token: {SHOPIFY_ACCESS_TOKEN}`
- **Scopes**: Apps must request specific access scopes during installation

### Parameters

#### Path Parameters
- **shop** (string) - Required - Your Shopify store domain (e.g., your-store.myshopify.com)
- **version** (string) - Required - API version (e.g., 2026-01, 2025-10)

#### Request Body
- **query** (string) - Required - GraphQL query or mutation string

### Request Examples

#### 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
```
curl -X POST \
  https://{shop}.myshopify.com/admin/api/2026-01/graphql.json \
  -H 'Content-Type: application/json' \
  -H 'X-Shopify-Access-Token: {SHOPIFY_ACCESS_TOKEN}' \
  -d '{
    "query": "query { shop { name } }"
  }'
```

### Response

#### Success Response (200)
- **data** (object) - The requested GraphQL data
- **errors** (array) - Optional - Array of error objects if any errors occurred

#### Response Example
```
{
  "data": {
    "shop": {
      "name": "My Store"
    }
  }
}
```

### Security Considerations
- Keep access tokens secure and never expose them in client-side code
- Request only the minimum required access scopes
- Tokens are generated via OAuth for public and custom apps in Dev Dashboard
- Custom apps created in Shopify admin are authenticated through the admin interface
```

--------------------------------

### Query GraphQL Admin API - React Router

Source: https://shopify.dev/docs/api/admin-graphql/latest

Authenticate and execute a GraphQL query in a React Router loader function using Shopify's authentication middleware. Returns shop data by querying the shop name field.

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

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

--------------------------------

### Handle HTTP 423 Locked Error Response (Shopify Admin GraphQL)

Source: https://shopify.dev/docs/api/admin-graphql/latest

This snippet illustrates an HTTP 423 Locked error response, indicating that the shop is currently unavailable, possibly due to maintenance or other restrictions. The JSON response provides a message confirming the shop's unavailability.

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

--------------------------------

### Handle Shopify Admin GraphQL API Internal Server Error (JSON)

Source: https://shopify.dev/docs/api/admin-graphql/latest

This JSON snippet demonstrates a 200 OK response from the Shopify Admin GraphQL API indicating an internal server error. It provides a generic error message, the 'INTERNAL_SERVER_ERROR' code, and a request ID that should be included in support requests for debugging purposes. This error suggests an issue on Shopify's end.

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

--------------------------------

### HTTP Status Codes

Source: https://shopify.dev/docs/api/admin-graphql/latest

Reference for HTTP status codes returned by the Shopify Admin GraphQL API. While most errors return HTTP 200, certain conditions return specific 4xx and 5xx status codes.

```APIDOC
## HTTP Status Codes

### 200 OK
Request was successful. Check the response body for any errors in the errors array.

### 400 Bad Request
The server will not process the request.

### 402 Payment Required
The shop is frozen. The shop owner will need to pay the outstanding balance to unfreeze the shop.

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

### 404 Not Found
The resource isn't available. This is often caused by querying for something that's been deleted.

### 423 Locked
The shop isn't available. This can happen when stores repeatedly exceed API rate limits or due to fraud risk.

### 5xx Errors
An internal error occurred in Shopify. Check out the Shopify status page for more information.

### Notes
- 4xx and 5xx errors occur infrequently and are often related to network communications, your account, or an issue with Shopify's services
- Many errors that would typically return a 4xx or 5xx status code return an HTTP 200 response instead
- Refer to the error response structure documentation for details on how to parse errors in 200 responses
```

--------------------------------

### Error Response - 500 Internal Server Error

Source: https://shopify.dev/docs/api/admin-graphql/latest

Returned when an unexpected error occurs on the Shopify server. This indicates a server-side issue that prevented the request from being processed successfully.

```APIDOC
## Error Response - 500 Internal Server Error

### Description
Returned when an unexpected error occurs on the Shopify server.

### HTTP Status Code
500 Internal Server Error

### Error Response
```json
{
  "errors": "An unexpected error occurred"
}
```

### Possible Causes
- Temporary server issue
- Service outage or degradation
- Unhandled exception on the server
- Recommendation: Retry the request with exponential backoff
```

--------------------------------

### Error Response - 400 Bad Request

Source: https://shopify.dev/docs/api/admin-graphql/latest

Returned when a required parameter is missing or invalid in the API request. This error indicates that the query or request body contains malformed or incomplete data that the API cannot process.

```APIDOC
## Error Response - 400 Bad Request

### Description
Returned when a required parameter is missing or invalid in the API request.

### HTTP Status Code
400 Bad Request

### Error Response
```json
{
  "errors": {
    "query": "Required parameter missing or invalid"
  }
}
```

### Possible Causes
- Missing required query parameters
- Invalid parameter format or type
- Malformed GraphQL query syntax
```

--------------------------------

### Handle HTTP 500 Internal Server Error Response (Shopify Admin GraphQL)

Source: https://shopify.dev/docs/api/admin-graphql/latest

This snippet demonstrates an HTTP 500 Internal Server Error response, indicating an unexpected issue occurred on the server side. The JSON response contains a generic message about the unexpected error.

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

--------------------------------

### Common Error Codes

Source: https://shopify.dev/docs/api/admin-graphql/latest

Reference for common error codes returned by the Shopify Admin GraphQL API. These codes indicate specific error conditions such as rate limiting, authentication failures, and service issues.

```APIDOC
## Common Error Codes

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

**Example Response:**
```json
{
  "errors": [
    {
      "message": "Query cost is 2003, which exceeds the single query max cost limit (1000).\n\nSee https://shopify.dev/concepts/about-apis/rate-limits for more information on how the cost of a query is calculated.\n\nTo query larger amounts of data with fewer limits, bulk operations should be used instead.\nSee 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"
      }
    }
  ]
}
```

### ACCESS_DENIED
The client doesn't 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.

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

--------------------------------

### Error Response Structure

Source: https://shopify.dev/docs/api/admin-graphql/latest

Describes the structure of error responses returned by the Shopify Admin GraphQL API. All errors include a message field with details and an extensions object containing error codes and metadata.

```APIDOC
## Error Response Structure

### Description
The Shopify Admin GraphQL API returns errors in a standardized format. Most errors that would typically return 4xx or 5xx status codes instead return HTTP 200 with error details in the response body.

### Response Structure

#### Root Properties
- **errors** (array) - Required - A list of all errors returned

#### Error Object Properties
- **message** (string) - Required - Contains details about the error(s)
- **extensions** (object) - Required - Provides more information about the error(s) including properties and metadata

#### Extensions Object Properties
- **code** (string) - Required - Shows error codes common to Shopify. Additional error codes may also be shown
- **documentation** (string) - Optional - Link to documentation for the error
- **cost** (number) - Optional - Query cost when applicable
- **maxCost** (number) - Optional - Maximum allowed cost when applicable
- **requestId** (string) - Optional - Request ID for support inquiries

### Response Example
```json
{
  "errors": [
    {
      "message": "Error message describing what went wrong",
      "extensions": {
        "code": "ERROR_CODE",
        "documentation": "https://shopify.dev/api/..."
      }
    }
  ]
}
```
```

--------------------------------

### Handle Shopify Admin GraphQL API Query Cost Exceeded Error (JSON)

Source: https://shopify.dev/docs/api/admin-graphql/latest

This JSON snippet illustrates a 200 OK response from the Shopify Admin GraphQL API when a query exceeds the maximum allowed cost. It includes details about the 'MAX_COST_EXCEEDED' error code, the actual cost, the maximum allowed cost, and documentation links for rate limits and bulk operations. This type of error indicates that the client needs to optimize their queries or use bulk operations.

```json
{
"errors": [
  {
    "message": "Query cost is 2003, which exceeds the single query max cost limit (1000).\n\nSee https://shopify.dev/concepts/about-apis/rate-limits for more information on how the\ncost of a query is calculated.\n\nTo query larger amounts of data with fewer limits, bulk operations should be used instead.\nSee https://shopify.dev/tutorials/perform-bulk-operations-with-admin-api for usage details.\n",
    "extensions": {
      "code": "MAX_COST_EXCEEDED",
      "cost": 2003,
      "maxCost": 1000,
      "documentation": "https://shopify.dev/api/usage/limits#rate-limits"
    }
  }
]
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.