Saltar al contenido principal
La API de Reval expone los datos de suscripciones de tu tienda para que los lleves a tu BI, tu data warehouse o tus automatizaciones, y te deja operarlas: pausar, cancelar, saltear, cambiar productos y dirección. Es GraphQL, y cada clave ve y opera únicamente la tienda que la generó.
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:
Si tu cliente no te deja usar Authorization, el header X-Reval-Api-Key es equivalente.
  • Una clave revocada deja de funcionar al instante. Las consultas reciben 401 con el código UNAUTHENTICATED.
  • 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.
Las respuestas incluyen datos personales de tus clientes (email, dirección, teléfono, documento fiscal). Tratá las claves como una contraseña: no las pegues en código que se publique ni las compartas por chat.

Primera consulta

El endpoint acepta introspección, así que cualquier cliente GraphQL (GraphiQL, Insomnia, Postman, Altair) te muestra el esquema completo con la descripción de cada campo. Esta página es el resumen; la referencia del esquema tiene todos los tipos y campos.
  • Solo se acepta POST con un body JSON { "query", "variables", "operationName" }: una operación por request, sin batching ni GET.
  • 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 campo currency del 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ís first elementos y seguís con after usando el endCursor de la página anterior.
  • nodes es el atajo cuando no necesitás el cursor de cada fila.
  • totalCount cuenta todas las filas que cumplen el filtro, no solo la página.
  • reverse: true invierte el orden (de más antiguo a más nuevo).
  • Los listados anidados (subscription.orders, customer.subscriptions) se paginan igual.

Filtros

Cada listado acepta un filter con los campos más usados:
Para sincronizar un warehouse de forma incremental, pedí subscriptions(filter: { updatedAfter: "<última corrida>" }, sortKey: UPDATED_AT, reverse: true) y orders(filter: { createdAfter: "<última corrida>" }).

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 un extensions.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 recibe 403 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 header Idempotency-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.
El header es opcional, pero sin él un reintento puede saltear dos ciclos o cancelar dos veces.

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
Cancelar con motivo y nota
Cambiar productos
Link al portal para un email de retención

Ejemplos

Suscripciones activas con sus productos y el próximo cobro
Un cliente con todo su historial
Bajas del mes, con motivo
Planes y cajas publicados