Las consultas están en las secciones siguientes; las acciones, en Acciones. La lista completa de tipos y campos está en la referencia del esquema, y hay recetas para los casos más comunes. Para enterarte de lo que pasa sin consultar, están los webhooks.
Autenticación
Las claves se generan en Reval → Integraciones en tu admin de Shopify. Ponele el nombre de la herramienta que la va a usar («Triple Whale», «Looker») y guardá la clave en el momento: se muestra completa una sola vez. Después, la lista solo muestra el prefijo. Mandá la clave en cada request como Bearer token:Authorization, el header X-Reval-Api-Key es equivalente.
- Una clave revocada deja de funcionar al instante. Las consultas reciben
401con el códigoUNAUTHENTICATED. - Reval guarda solo un hash de la clave. Si la perdés, revocala y generá otra.
- Podés tener hasta 25 claves activas por tienda, cada una con un nombre de hasta 60 caracteres. La lista muestra el último uso de cada una, así sabés cuáles revocar.
- Al generar la clave elegís lectura y escritura o solo lectura. Una clave de solo lectura consulta todo pero no puede ejecutar acciones (ver Acciones). El tipo no se cambia después: revocá y generá otra.
Primera consulta
- Solo se acepta
POSTcon un body JSON{ "query", "variables", "operationName" }: una operación por request, sin batching niGET. - El endpoint responde a CORS, así que una herramienta en el navegador puede llamarlo. No lo hagas desde el front de tu tienda: la clave quedaría expuesta a cualquiera que abra el código fuente.
Qué podés consultar
Los objetos que existen en Shopify traen su GID de Shopify para cruzarlos con la Admin API:
shopifyOrderId, shopifyCustomerId, shopifyVariantId, shopifyProductId. Los identificadores de Mercado Pago (mercadoPagoPreapprovalId, mercadoPagoPaymentId) sirven para conciliar contra tu cuenta de MP; las credenciales nunca se exponen.
Convenciones
- Montos (
Money) son strings con dos decimales:"18500.00". La moneda está en el campocurrencydel mismo objeto. - Fechas (
DateTime) son ISO-8601 en UTC:"2026-11-02T13:00:00.000Z". - Enums van en mayúsculas:
ACTIVE,PAUSED,CANCELLED,MONTHS,PERCENT,DYNAMIC_BOX. - Los IDs de Reval son opacos; usá siempre el que devolvió la API.
Paginación
Todos los listados son connections al estilo Shopify: pedísfirst elementos y seguís con after usando el endCursor de la página anterior.
nodeses el atajo cuando no necesitás el cursor de cada fila.totalCountcuenta todas las filas que cumplen el filtro, no solo la página.reverse: trueinvierte el orden (de más antiguo a más nuevo).- Los listados anidados (
subscription.orders,customer.subscriptions) se paginan igual.
Filtros
Cada listado acepta unfilter con los campos más usados:
Límites
Los límites existen para que un integrador que consulta mucho nunca afecte el checkout ni los cobros. Cuando una consulta los supera, la respuesta dice cuál:
La profundidad cuenta objetos del modelo:
subscriptions › items › plan › group son cuatro niveles. edges, node, nodes y pageInfo no cuentan.
Cada respuesta trae los headers X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset (epoch en segundos) para que tu cliente se regule solo.
Errores
Los errores siguen el formato GraphQL, con unextensions.code para que tu código decida:
Las reglas de negocio de las acciones (estado inválido, compromiso mínimo, plan archivado, rechazo de Mercado Pago) no son errores: vuelven en
userErrors con 200. Ver Acciones.
Acciones
Además de consultar, la API permite operar las suscripciones de tu tienda con las mismas acciones que el merchant hace en el admin: pausar, reanudar, cancelar, saltear la próxima entrega, cambiar productos y cantidades, actualizar la dirección y generar un link al portal. También permite armar links de checkout con varios productos y los datos del cliente ya cargados, para que un bot cierre la venta con un link listo. Son mutations GraphQL en el mismo endpoint. Cada acción tiene exactamente los mismos efectos que desde el admin: Mercado Pago se actualiza primero (si rechaza, no cambia nada en Reval), se recalculan precio y envío cuando corresponde, se emiten los mismos eventos a Klaviyo, Flow y a tus webhooks, y el historial de la suscripción muestra «API (nombre de la clave)» como autor.Claves de solo lectura
Al generar una clave en Reval → Integraciones elegís si es de lectura y escritura o de solo lectura. Una clave de solo lectura puede ejecutar cualquier consulta, pero toda mutation recibe403 con el código FORBIDDEN_READ_ONLY. Usala para dashboards y reportes; reservá las de escritura para las automatizaciones que realmente actúan.
Idempotencia
Las acciones mueven cobros y envíos reales, así que un reintento (timeout, caída de tu worker) no puede repetirlas. Mandá un headerIdempotency-Key con un identificador único por operación (un UUID). Si la misma clave llega de nuevo con el mismo body dentro de las 24 horas, la API devuelve la respuesta original sin ejecutar nada y marca el header Idempotency-Replayed: true. Si llega con otro body, responde 422 con IDEMPOTENCY_KEY_REUSED: es un bug de tu lado, no una segunda operación.
Errores de negocio: userErrors
Una mutation nunca falla con un error GraphQL por una regla de negocio. Devuelve 200 con un payload que trae el objeto o una lista userErrors con un code para que tu código decida, y la suscripción queda igual:
Mutations disponibles
Todas devuelven
{ subscription, userErrors }, salvo subscriptionPortalLink y checkoutLinkCreate, que devuelven { url, expiresAt, userErrors }.
Pausar desde un bot de soporte