09 · Admin GraphQL API

Qué es y por qué existe

Cuando construyes una app para Shopify — no un theme, sino una app — el Admin GraphQL API es tu acceso principal al back-office del comerciante. Con el permiso del comerciante (OAuth), tu app puede leer pedidos, crear o actualizar productos, gestionar clientes, escribir metafields, y disparar prácticamente cualquier operación que un comerciante haría manualmente desde su panel.

El endpoint del Admin API tiene la forma:

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

La diferencia estructural respecto al Storefront API: el Admin API opera con el token de acceso del comerciante, no con un token público. Ese token se obtiene a través del flujo OAuth de instalación de app y se almacena en el servidor de tu app. Nunca lo envías al cliente.

La razón por la que Shopify tiene REST además de GraphQL en el Admin es histórica — REST llegó primero (2009), GraphQL se agregó en 2019. Desde entonces, el GraphQL API es el que recibe toda la inversión: nuevas features, mejor performance, bulk operations, introspección completa. El REST API está en modo mantenimiento. Esta sección enseña exclusivamente GraphQL.

Autenticación y scopes

El Admin API requiere el header X-Shopify-Access-Token con el access token del comerciante. Ese token se obtiene al completar el flujo OAuth de instalación. Para los scripts del tutorial lo obtienes directamente en Admin → Apps → tu app → API credentials → Admin API access token. Guárdalo en ~/proyectos/shopify/brew-atlas/brew-atlas-app/.env bajo la clave SHOPIFY_ADMIN_TOKEN. Este token es secreto de servidor — nunca lo expongas al cliente ni lo incluyas en el repositorio.

Los permisos que tu app puede ejercer se declaran en shopify.app.toml bajo la clave scopes:

# shopify.app.toml
[access_scopes]
scopes = "read_products,write_products,read_orders,read_customers"

Cuando el comerciante instala la app, ve exactamente qué permisos está otorgando y acepta. Si tu app pide un scope que no declaró en el toml, la API rechaza la operación con un error de permisos — no HTTP 401, sino un userError o un error de schema.

Los scopes siguen el patrón read_X / write_X. write_X incluye implícitamente read_X. Los scopes disponibles cubren productos, pedidos, clientes, inventario, metafields, webhooks, páginas, y docenas de recursos más.

Queries del Admin API

La sintaxis de queries es GraphQL estándar. Lo que difiere es el schema — el Admin API expone el modelo completo de datos de la tienda, no solo la vista del comprador.

# Query: últimos 10 pedidos con cliente y total
query RecentOrders($first: Int!) {
  orders(first: $first, reverse: true) {
    edges {
      node {
        id
        name
        createdAt
        displayFinancialStatus
        totalPriceSet {
          shopMoney {
            amount
            currencyCode
          }
        }
        customer {
          displayName
          email
        }
        lineItems(first: 5) {
          edges {
            node {
              title
              quantity
              originalUnitPriceSet {
                shopMoney { amount currencyCode }
              }
            }
          }
        }
      }
    }
  }
}

La diferencia más visible respecto al Storefront API: los precios se representan como MoneyBag con shopMoney (en la moneda de la tienda) y presentmentMoney (en la moneda de presentación al cliente). Esto existe porque el Admin ve ambas monedas simultáneamente — el comerciante necesita saber cuánto cobró en cada moneda.

Mutations y el patrón userErrors

Todas las mutations del Admin API siguen el mismo patrón de respuesta: el recurso modificado y un array userErrors. Este array contiene errores de validación de negocio — condiciones que hacen que la operación sea inválida pero que no producen un error HTTP.

mutation ProductUpdate($input: ProductInput!) {
  productUpdate(input: $input) {
    product {
      id
      title
      status
    }
    userErrors {
      field
      message
    }
  }
}

Con variables:

{
  "input": {
    "id": "gid://shopify/Product/1234567890",
    "title": "Geisha Washed — La Palma",
    "status": "ACTIVE"
  }
}

Si la operación es exitosa, userErrors es un array vacío y product contiene el recurso actualizado. Si hay un error de validación (por ejemplo, un título que viola alguna regla de negocio), product es null y userErrors contiene los detalles. El HTTP status code es 200 en ambos casos.

Este patrón es consistente en todo el Admin API. Siempre verifica userErrors antes de asumir que la operación fue exitosa — no basta con que el HTTP status sea 200.

Paginación

El Admin API usa paginación basada en cursor. El patrón es first / after para avanzar, last / before para retroceder:

query Products($first: Int!, $after: String) {
  products(first: $first, after: $after) {
    pageInfo {
      hasNextPage
      endCursor
    }
    edges {
      cursor
      node {
        id
        title
      }
    }
  }
}

Para paginar, tomas el endCursor de la respuesta y lo pasas como after en la siguiente query. El pageInfo.hasNextPage te dice si hay más datos.

Para datasets grandes (miles o decenas de miles de registros), la paginación manual es lenta y costosa en términos de rate limiting. Para esos casos, usa bulk operations.

Rate limiting basado en costo

El Admin API no usa rate limiting por conteo de requests — usa un sistema de costo por query. Cada query tiene un costo calculado basado en la complejidad de los campos solicitados y la cantidad de objetos que puede retornar. El bucket por defecto es de 1000 puntos para tiendas estándar (más para Plus y cuentas de partner). El bucket se restaura a 50 puntos por segundo.

Cuando ejecutás una query, la respuesta incluye en extensions.cost el costo de esa query específica y el estado actual de tu bucket:

{
  "data": { ... },
  "extensions": {
    "cost": {
      "requestedQueryCost": 32,
      "actualQueryCost": 15,
      "throttleStatus": {
        "maximumAvailable": 1000.0,
        "currentlyAvailable": 985.0,
        "restoreRate": 50.0
      }
    }
  }
}

requestedQueryCost es el costo calculado antes de ejecutar (basado en first: N). actualQueryCost es el costo real después de ejecutar (basado en cuántos objetos realmente devolvió). Shopify te cobra el costo real, no el estimado.

Cuando el bucket se agota, Shopify devuelve un error con el código THROTTLED y el campo extensions.cost.throttleStatus.restoreRate te dice cuántos puntos por segundo se van a restaurar. El header Retry-After indica cuántos segundos esperar. Implementá backoff exponencial en tu cliente.

Creá ~/proyectos/shopify/brew-atlas/scripts/utils/admin-client.ts:

// brew-atlas/scripts/utils/admin-client.ts
async function queryWithRetry(
  client: ReturnType<typeof createAdminApiClient>,
  query: string,
  variables: Record<string, unknown>,
  retries = 3
): Promise<unknown> {
  for (let attempt = 0; attempt <= retries; attempt++) {
    try {
      const { data, errors } = await client.request(query, { variables });
      if (errors?.length) throw new Error(JSON.stringify(errors));
      return data;
    } catch (err: unknown) {
      const message = err instanceof Error ? err.message : String(err);
      if (message.includes('THROTTLED') && attempt < retries) {
        const wait = Math.pow(2, attempt) * 1000;
        await new Promise((r) => setTimeout(r, wait));
        continue;
      }
      throw err;
    }
  }
}

Bulk Operations

Para exportar o procesar miles o millones de registros, las bulk operations son el mecanismo correcto. En lugar de paginar manualmente, le pides a Shopify que ejecute la query en background y te entregue los resultados como un archivo JSONL descargable.

# Paso 1: iniciar la bulk operation
mutation {
  bulkOperationRunQuery(
    query: """
    {
      products {
        edges {
          node {
            id
            title
            status
            variants {
              edges {
                node {
                  id
                  sku
                  price
                  inventoryQuantity
                }
              }
            }
          }
        }
      }
    }
    """
  ) {
    bulkOperation {
      id
      status
    }
    userErrors {
      field
      message
    }
  }
}

# Paso 2: consultar el estado (polling)
query BulkOperationStatus {
  currentBulkOperation {
    id
    status
    errorCode
    objectCount
    url
  }
}

Cuando status es COMPLETED, url contiene una URL pre-firmada de S3 desde donde puedes descargar el archivo JSONL. El archivo tiene un objeto por línea — productos, variantes, etc. — en el orden de la query.

Las bulk operations no consumen el rate limiting de costo — tienen su propio sistema de colas. Solo puede haber una bulk operation activa por tienda a la vez. Si inicias una segunda, la primera se cancela.

Para mutaciones masivas (actualizar miles de precios, metafields, etc.), existe bulkOperationRunMutation con un archivo de entrada JSONL.

Webhooks

Los webhooks permiten que Shopify notifique a tu app cuando ocurren eventos en la tienda. En lugar de hacer polling a la API cada N segundos para ver si hubo pedidos nuevos, Shopify llama a tu endpoint HTTP cuando un pedido se crea.

Declaración en shopify.app.toml (recomendado — el CLI los despliega automáticamente):

# shopify.app.toml
[[webhooks.subscriptions]]
topics = ["orders/create", "orders/updated"]
uri = "/webhooks"
 
[[webhooks.subscriptions]]
topics = ["products/update"]
uri = "/webhooks/products"

O creación programática vía Admin API:

mutation WebhookSubscriptionCreate($topic: WebhookSubscriptionTopic!, $webhookSubscription: WebhookSubscriptionInput!) {
  webhookSubscriptionCreate(topic: $topic, webhookSubscription: $webhookSubscription) {
    webhookSubscription {
      id
      topic
      endpoint {
        ... on WebhookHttpEndpoint {
          callbackUrl
        }
      }
    }
    userErrors { field message }
  }
}

Validación de firma HMAC: Shopify firma cada webhook con HMAC-SHA256 usando el client secret de tu app. Tu endpoint debe validar esa firma antes de procesar el payload — de lo contrario, cualquiera podría enviar requests falsos a tu endpoint.

Creá ~/proyectos/shopify/brew-atlas/brew-atlas-app/app/webhooks/validate.ts:

// brew-atlas/app/webhooks/validate.ts
import { createHmac, timingSafeEqual } from 'node:crypto';
 
export function validateWebhookSignature(
  rawBody: string,
  hmacHeader: string,
  secret: string
): boolean {
  const computed = createHmac('sha256', secret)
    .update(rawBody, 'utf8')
    .digest('base64');
  return timingSafeEqual(
    Buffer.from(computed),
    Buffer.from(hmacHeader)
  );
}

Usa timingSafeEqual siempre — la comparación de strings regular es vulnerable a timing attacks.

Puentes mentales

Estado 2026

Lo relevante al 2026:

• Versión estable: 2026-04. El Admin API y el Storefront API comparten el mismo calendario de versiones y el mismo modelo de soporte (≥12 meses por versión estable).
• REST deprecado en la práctica: el REST API sigue funcionando y recibe fixes de seguridad, pero las features nuevas (metaobjetos, bulk mutations, funciones) solo están en GraphQL. Para código nuevo, GraphQL siempre.
• @shopify/admin-api-client: el cliente oficial de Shopify para Node. Maneja la serialización, los headers, y expone TypeScript types generados desde el schema. Úsalo en lugar de fetch crudo para reducir boilerplate.
• Scopes granulares: desde 2024, algunos recursos tienen scopes más granulares. Revisá la documentación de cada recurso para ver el scope específico necesario.

Sintaxis y anatomía

Cliente de Admin API en TypeScript con el paquete oficial. Creá ~/proyectos/shopify/brew-atlas/scripts/sync-orders.ts:

// brew-atlas/scripts/sync-orders.ts
import { createAdminApiClient } from '@shopify/admin-api-client';
import { writeFileSync } from 'node:fs';
import { join } from 'node:path';
 
const client = createAdminApiClient({
  storeDomain: process.env.SHOPIFY_STORE ?? 'brew-atlas-dev.myshopify.com',
  apiVersion: '2026-04',
  accessToken: process.env.SHOPIFY_ADMIN_TOKEN!,
});
 
const ORDERS_QUERY = /* GraphQL */ `
  query RecentOrders($first: Int!) {
    orders(first: $first, reverse: true) {
      edges {
        node {
          id
          name
          createdAt
          displayFinancialStatus
          totalPriceSet {
            shopMoney { amount currencyCode }
          }
          customer {
            displayName
            email
          }
        }
      }
    }
  }
`;
 
async function syncOrders() {
  const { data, errors } = await client.request(ORDERS_QUERY, {
    variables: { first: 50 },
  });
 
  if (errors) {
    console.error('GraphQL errors:', errors);
    process.exit(1);
  }
 
  const rows = data.orders.edges.map(({ node }: {
    node: {
      name: string;
      createdAt: string;
      displayFinancialStatus: string;
      totalPriceSet: { shopMoney: { amount: string; currencyCode: string } };
      customer: { displayName: string; email: string } | null;
    };
  }) => [
    node.name,
    node.createdAt,
    node.displayFinancialStatus,
    `${node.totalPriceSet.shopMoney.amount} ${node.totalPriceSet.shopMoney.currencyCode}`,
    node.customer?.displayName ?? '',
    node.customer?.email ?? '',
  ].join(','));
 
  const csv = [
    'order,created_at,status,total,customer_name,customer_email',
    ...rows,
  ].join('\n');
 
  const outPath = join(import.meta.dirname, 'out', 'orders.csv');
  writeFileSync(outPath, csv, 'utf-8');
  console.log(`Exported ${rows.length} orders to ${outPath}`);
}
 
syncOrders().catch(console.error);

Y un ejemplo de bulk operation para exportar todo el catálogo con variantes:

// Fragmento: iniciar bulk operation de productos
const BULK_MUTATION = /* GraphQL */ `
  mutation {
    bulkOperationRunQuery(
      query: """
      {
        products {
          edges {
            node {
              id
              title
              handle
              status
              variants {
                edges {
                  node {
                    id
                    sku
                    price
                    inventoryQuantity
                  }
                }
              }
            }
          }
        }
      }
      """
    ) {
      bulkOperation { id status }
      userErrors { field message }
    }
  }
`;
 
const { data } = await client.request(BULK_MUTATION);
if (data.bulkOperationRunQuery.userErrors.length) {
  throw new Error(JSON.stringify(data.bulkOperationRunQuery.userErrors));
}
console.log('Bulk operation started:', data.bulkOperationRunQuery.bulkOperation.id);
// Hacer polling a currentBulkOperation hasta status === 'COMPLETED'
// Luego descargar el JSONL desde data.currentBulkOperation.url

Proyecto · Brew Atlas

npm install @shopify/admin-api-client

mkdir -p ~/proyectos/shopify/brew-atlas/scripts/out && npx tsx ~/proyectos/shopify/brew-atlas/scripts/sync-orders.ts

Errores comunes

Checklist senior

Siguiente

Con las dos APIs de GraphQL cubiertas — Storefront para el comprador, Admin para el comerciante — el siguiente bloque entra en el mundo de las extensiones: cómo tu app inyecta UI en un theme estándar sin modificar el código del theme directamente. Eso es el territorio de las Theme App Extensions.