Shopify Hello World Skill

Shopify Hello World

Overview

Minimal working example: query your store's products using the Shopify GraphQL Admin API. Uses @shopify/shopify-api with a custom app access token for zero-friction setup.

Prerequisites

Completed shopify-install-auth setup
A Shopify development store
An Admin API access token (shpat_xxx) from Settings > Apps > Develop apps

Instructions

Step 1: Create Project

mkdir shopify-hello-world && cd shopify-hello-world
npm init -y
npm install @shopify/shopify-api dotenv

Step 2: Configure Environment

# .env
SHOPIFY_STORE=your-store.myshopify.com
SHOPIFY_ACCESS_TOKEN=shpat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
SHOPIFY_API_KEY=your_api_key
SHOPIFY_API_SECRET=your_api_secret

Step 3: Write the Hello World Script

// hello-shopify.ts
import "@shopify/shopify-api/adapters/node";
import { shopifyApi } from "@shopify/shopify-api";
import "dotenv/config";

const shopify = shopifyApi({
  apiKey: process.env.SHOPIFY_API_KEY!,
  apiSecretKey: process.env.SHOPIFY_API_SECRET!,
  hostName: "localhost",
  apiVersion: "2024-10",
  isCustomStoreApp: true,
  adminApiAccessToken: process.env.SHOPIFY_ACCESS_TOKEN!,
});

async function main() {
  const session = shopify.session.customAppSession(
    process.env.SHOPIFY_STORE!
  );

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

  // Query shop info
  const shopInfo = await client.request(`{
    shop {
      name
      currencyCode
      primaryDomain { url }
    }
  }`);
  console.log("Store:", shopInfo.data.shop.name);
  console.log("Currency:", shopInfo.data.shop.currencyCode);

  // Query first 5 products
  const products = await client.request(`{
    products(first: 5) {
      edges {
        node {
          id
          title
          status
          totalInventory
          variants(first: 3) {
            edges {
              node {
                title
                price
                sku
                inventoryQuantity
              }
            }
          }
        }
      }
    }
  }`);

  console.log("\nProducts:");
  for (const edge of products.data.products.edges) {
    const p = edge.node;
    console.log(`  - ${p.title} (${p.status}, ${p.totalInventory} in stock)`);
    for (const v of p.variants.edges) {
      console.log(`      Variant: ${v.node.title} — $${v.node.price} (SKU: ${v.node.sku})`);
    }
  }

  console.log("\nSuccess! Your Shopify connection is working.");
}

main().catch((err) => {
  console.error("Failed:", err.message);
  if (err.response) {
    console.error("Response:", JSON.stringify(err.response.body, null, 2));
  }
  process.exit(1);
});

Step 4: Run It

npx tsx hello-shopify.ts
# Or compile first:
npx tsc hello-shopify.ts && node hello-shopify.js

Output

Expected console output:

Store: My Dev Store
Currency: USD

Products:
  - Classic T-Shirt (ACTIVE, 150 in stock)
      Variant: Small — $29.99 (SKU: TSH-SM)
      Variant: Medium — $29.99 (SKU: TSH-MD)
      Variant: Large — $29.99 (SKU: TSH-LG)
  - Coffee Mug (ACTIVE, 42 in stock)
      Variant: Default Title — $14.99 (SKU: MUG-01)

Success! Your Shopify connection is working.

Error Handling

| Error | Cause | Solution | |-------|-------|----------| | HttpResponseError: 401 Unauthorized | Invalid or revoked access token | Regenerate token in Shopify admin > Settings > Apps | | HttpResponseError: 403 Forbidden | Token lacks required scopes | Enable read_products scope in app config | | HttpResponseError: 404 Not Found | Wrong store domain or API version | Verify store URL is *.myshopify.com | | ENOTFOUND your-store.myshopify.com | Store domain typo or DNS issue | Double-check SHOPIFY_STORE value | | GraphqlQueryError with userErrors | Invalid query syntax | Check field names against API version docs | | MODULE_NOT_FOUND @shopify/shopify-api | Package not installed | Run npm install @shopify/shopify-api |

Examples

Create a Product via GraphQL Mutation

const response = await client.request(`
  mutation productCreate($input: ProductCreateInput!) {
    productCreate(product: $input) {
      product {
        id
        title
        handle
      }
      userErrors {
        field
        message
      }
    }
  }
`, {
  variables: {
    input: {
      title: "Hello World Product",
      descriptionHtml: "<p>Created via Shopify API</p>",
      vendor: "My App",
      productType: "Test",
      tags: ["api-created", "hello-world"],
    },
  },
});

if (response.data.productCreate.userErrors.length > 0) {
  console.error("Errors:", response.data.productCreate.userErrors);
} else {
  console.log("Created:", response.data.productCreate.product.title);
}

REST Admin API (Legacy but Still Supported)

const restClient = new shopify.clients.Rest({ session });

// GET /admin/api/2024-10/products.json
const { body } = await restClient.get({
  path: "products",
  query: { limit: 5, status: "active" },
});

console.log("Products:", body.products.map((p: any) => p.title));

Resources

Next Steps

Proceed to shopify-local-dev-loop for development workflow setup.

Agent Skills: Shopify Hello World

Install this agent skill to your local

Skill Files