Shopify Admin Api

Shopify Admin API

Overview

The Shopify Admin API gives apps full access to a merchant's store data — products, variants, orders, customers, inventory, metafields, and more. It is available in both GraphQL (recommended) and REST flavors, with GraphQL offering precise field selection, bulk operations, and better rate limiting via the calculated cost system. Use the @shopify/shopify-api Node.js library or direct HTTP calls with an Admin API access token.

When to Use This Skill

• When reading or writing product catalog data (titles, variants, pricing, images, inventory)
• When fulfilling or updating orders programmatically from an external system
• When syncing customer records between Shopify and a CRM or ERP
• When running bulk data exports or imports using Bulk Operations
• When building an internal tool that needs merchant store access via a Custom App token
• When automating inventory adjustments from a warehouse management system

Core Instructions

1. Obtain an Admin API access token

For a custom app (single store), create it in Admin → Settings → Apps and Sales Channels → Develop apps. For a public/partner app, the token is obtained after OAuth (see @shopify-app-development).

   # .env
   SHOPIFY_ADMIN_API_TOKEN=shpat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
   SHOPIFY_SHOP=mystore.myshopify.com
   SHOPIFY_API_VERSION=2025-01

2. Initialize the Admin API client

   // lib/shopify-admin.ts
   import { shopifyApi, ApiVersion, Session } from "@shopify/shopify-api";
   import "@shopify/shopify-api/adapters/node";

   const shopify = shopifyApi({
     apiKey: process.env.SHOPIFY_API_KEY!,
     apiSecretKey: process.env.SHOPIFY_API_SECRET!,
     scopes: ["read_products", "write_products", "read_orders", "write_orders"],
     hostName: process.env.SHOPIFY_APP_URL!,
     apiVersion: ApiVersion.January25,
     isEmbeddedApp: false, // true for merchant-facing embedded apps
   });

   // For custom apps with a static token
   const session = new Session({
     id: `offline_${process.env.SHOPIFY_SHOP}`,
     shop: process.env.SHOPIFY_SHOP!,
     state: "",
     isOnline: false,
     accessToken: process.env.SHOPIFY_ADMIN_API_TOKEN,
   });

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

3. Query products with GraphQL

   // Fetch products with variants and inventory
   export async function getProducts(cursor?: string) {
     const response = await adminClient.request(`
       query GetProducts($cursor: String) {
         products(first: 50, after: $cursor) {
           pageInfo { hasNextPage endCursor }
           edges {
             node {
               id
               title
               status
               variants(first: 100) {
                 edges {
                   node {
                     id
                     sku
                     price
                     inventoryQuantity
                     inventoryItem { id }
                   }
                 }
               }
             }
           }
         }
       }
     `, { variables: { cursor } });
     return response.data.products;
   }

   // Update a product's price via mutation
   export async function updateVariantPrice(variantId: string, price: string) {
     const response = await adminClient.request(`
       mutation UpdateVariantPrice($id: ID!, $price: Money!) {
         productVariantUpdate(input: { id: $id, price: $price }) {
           productVariant { id price }
           userErrors { field message }
         }
       }
     `, { variables: { id: variantId, price } });

     const { userErrors } = response.data.productVariantUpdate;
     if (userErrors.length > 0) throw new Error(userErrors[0].message);
     return response.data.productVariantUpdate.productVariant;
   }

4. Fetch and update orders

   // Query unfulfilled orders
   export async function getUnfulfilledOrders() {
     const response = await adminClient.request(`
       query {
         orders(first: 50, query: "fulfillment_status:unfulfilled financial_status:paid") {
           edges {
             node {
               id
               name
               email
               createdAt
               lineItems(first: 50) {
                 edges {
                   node {
                     title
                     quantity
                     variant { id sku }
                   }
                 }
               }
               shippingAddress {
                 firstName lastName address1 city province zip country
               }
             }
           }
         }
       }
     `);
     return response.data.orders.edges.map(({ node }: any) => node);
   }

   // Mark an order as fulfilled
   export async function fulfillOrder(orderId: string, trackingNumber: string, trackingCompany: string) {
     // First get fulfillment order ID
     const orderResponse = await adminClient.request(`
       query GetFulfillmentOrders($id: ID!) {
         order(id: $id) {
           fulfillmentOrders(first: 5) {
             edges {
               node { id status lineItems(first: 20) { edges { node { id remainingQuantity } } } }
             }
           }
         }
       }
     `, { variables: { id: orderId } });

     const fulfillmentOrder = orderResponse.data.order.fulfillmentOrders.edges[0]?.node;
     if (!fulfillmentOrder) throw new Error("No fulfillment order found");

     const response = await adminClient.request(`
       mutation FulfillOrder($fulfillment: FulfillmentInput!) {
         fulfillmentCreate(fulfillment: $fulfillment) {
           fulfillment { id status }
           userErrors { field message }
         }
       }
     `, {
       variables: {
         fulfillment: {
           lineItemsByFulfillmentOrder: [{ fulfillmentOrderId: fulfillmentOrder.id }],
           trackingInfo: { number: trackingNumber, company: trackingCompany },
           notifyCustomer: true,
         },
       },
     });
     return response.data.fulfillmentCreate;
   }

5. Run Bulk Operations for large datasets

For exporting thousands of products or orders, use Bulk Operations (GraphQL only) — they run asynchronously and return a JSONL file URL:

   // Start a bulk operation
   export async function startBulkProductExport() {
     const response = await adminClient.request(`
       mutation {
         bulkOperationRunQuery(
           query: """
           {
             products {
               edges {
                 node {
                   id title status
                   variants {
                     edges {
                       node { id sku price inventoryQuantity }
                     }
                   }
                 }
               }
             }
           }
           """
         ) {
           bulkOperation { id status }
           userErrors { field message }
         }
       }
     `);
     return response.data.bulkOperationRunQuery.bulkOperation;
   }

   // Poll for completion and download URL
   export async function getBulkOperationStatus() {
     const response = await adminClient.request(`
       query {
         currentBulkOperation {
           id status errorCode
           objectCount
           url  # JSONL download URL — available when status is COMPLETED
         }
       }
     `);
     return response.data.currentBulkOperation;
   }

Examples

Customer search and update via REST API

// REST is still valid for simple lookups where GraphQL overhead isn't worth it
export async function searchCustomers(email: string) {
  const response = await restClient.get({
    path: "customers/search",
    query: { query: `email:${email}` },
  });
  return response.body.customers;
}

export async function tagCustomer(customerId: number, tags: string[]) {
  const response = await restClient.put({
    path: `customers/${customerId}`,
    data: { customer: { id: customerId, tags: tags.join(",") } },
  });
  return response.body.customer;
}

Inventory adjustment

export async function adjustInventory(inventoryItemId: string, locationId: string, delta: number) {
  const response = await adminClient.request(`
    mutation AdjustInventory($input: InventoryAdjustQuantitiesInput!) {
      inventoryAdjustQuantities(input: $input) {
        inventoryAdjustmentGroup {
          changes {
            name
            delta
            item { id }
            location { name }
          }
        }
        userErrors { field message }
      }
    }
  `, {
    variables: {
      input: {
        name: "available",
        reason: "correction",
        changes: [
          {
            inventoryItemId,
            locationId,
            delta,
          },
        ],
      },
    },
  });
  return response.data.inventoryAdjustQuantities;
}

Best Practices

• Prefer GraphQL over REST — GraphQL has a cost-based rate limit (1000 cost units/second) that's more forgiving than REST's 40 requests/second; it also avoids over-fetching
• Use Bulk Operations for exports above 250 records — never page through thousands of records manually; Bulk Operations handle up to millions of records in a single async job
• Always handle `userErrors` on mutations — a 200 HTTP response does not mean success; check userErrors array before treating a mutation as successful
• Use `gid://shopify/Product/123` format for IDs — Admin API GraphQL uses global IDs; never send numeric IDs without the GID prefix
• Implement exponential backoff — respect Retry-After headers and implement backoff on 429 and 503 responses
• Cache immutable product data — product titles and handles rarely change; cache them with a reasonable TTL to reduce API calls
• Scope to minimum required permissions — requesting fewer scopes reduces merchant trust friction at install time

Common Pitfalls

Related Skills

• @shopify-app-development
• @shopify-webhooks
• @shopify-metafields
• @shopify-storefront-api
• @bulk-data-operations

Large-Scale Product Catalog Export

Problem/Feature Description

A mid-sized e-commerce company runs a Shopify store with over 8,000 active products. Their data analytics team needs a complete snapshot of the product catalog — including each product's ID, title, status, and all variant details (SKU, price, inventory quantity) — to feed into their business intelligence dashboard. Previously, a developer tried to fetch everything with paginated API calls and the job kept timing out or hitting rate limits after a few hundred products.

The team wants a Node.js TypeScript script that reliably exports all products to a local JSONL file. The script should be executable from the command line, handle the entire product catalog without manual pagination, and be robust enough to run as a nightly job. Since the exported file will eventually be piped downstream, it should write results only when the export is fully finished. The team also wants to understand how the process works, so the script should log its progress to the console.

Output Specification

Produce a working TypeScript script (export-products.ts) that exports all products from a Shopify store. The script should:

• Accept Shopify store credentials via environment variables (SHOPIFY_ADMIN_API_TOKEN, SHOPIFY_SHOP, SHOPIFY_API_KEY, SHOPIFY_API_SECRET, SHOPIFY_APP_URL)
• Export product data including id, title, status, and all variants (id, sku, price, inventoryQuantity)
• Write the results to products-export.jsonl (one JSON object per line)
• Print progress/status messages to stdout as it runs

Also produce a brief README.md explaining how to install dependencies and run the script.

Customer Loyalty Tagging System

Problem/Feature Description

An e-commerce brand wants to implement a loyalty tier system in their Shopify store. After analyzing purchase history in their CRM, they have identified customers who qualify for "vip", "gold", or "silver" loyalty tiers. They need a script that applies these loyalty tags to the corresponding customer records in Shopify. Customer profiles may already carry labels from previous campaigns (such as "newsletter", "wholesale", "eu-customer"), and these must not be lost in the process.

The operation needs to handle a list of customer records, look each customer up by email address, and apply the appropriate loyalty tag. Since this involves many sequential API calls, the script must be resilient to rate limiting. The merchant has seen API errors before and needs the script to recover gracefully rather than failing partway through the list.

Output Specification

Produce a TypeScript script (tag-customers.ts) that:

• Reads a list of customer tag assignments from a JSON file (customers.json)
• For each customer, finds the customer in Shopify by email and adds the specified tag without disrupting any labels they already have
• Writes a results summary to tagging-results.json with the outcome for each customer (success/failure and final tags)
• Handles rate limiting gracefully

Also produce a package.json with necessary dependencies.

Input Files

The following files are provided as inputs. Extract them before beginning.

=============== FILE: customers.json =============== [ { "email": "alice@example.com", "tag": "vip" }, { "email": "bob@example.com", "tag": "gold" }, { "email": "carol@example.com", "tag": "silver" }, { "email": "david@example.com", "tag": "vip" }, { "email": "eve@example.com", "tag": "gold" } ]

Automated Order Fulfillment Service

Problem/Feature Description

A Shopify merchant runs a small warehouse operation. When orders are picked and packed, warehouse staff scan a barcode to generate a tracking number and want the system to automatically mark the corresponding Shopify order as fulfilled and notify the customer. Currently they do this manually through the Shopify admin dashboard, which is slow and error-prone.

You need to build a Node.js TypeScript module that can be called by the warehouse's internal system to fulfill a Shopify order given its numeric order ID and a tracking number. The module should look up any unfulfilled orders, and for a given order mark it as fulfilled with the provided tracking number. The merchant has a custom Shopify app with a static Admin API access token — there is no OAuth flow involved. The implementation needs to be production-quality: it should handle cases where the operation fails gracefully, including surface errors back to the caller clearly.

Output Specification

Produce a TypeScript module (fulfill-order.ts) that exports:

• A function fulfillOrder(orderId: string, trackingNumber: string, trackingCompany: string): Promise<void> that marks a Shopify order as fulfilled

Also produce a demo.ts script that demonstrates calling fulfillOrder with a sample order ID (e.g. "5678901234") and tracking details, printing success or error to the console. The demo should use environment variables for credentials (SHOPIFY_ADMIN_API_TOKEN, SHOPIFY_SHOP).

Include a package.json with the necessary dependencies.