Saltar para o conteúdo principal
A API da Reval expõe os dados de assinaturas da sua loja para você levá-los ao seu BI, ao seu data warehouse ou às suas automações, e permite operá-las: pausar, cancelar, pular, trocar produtos e endereço. É GraphQL, e cada chave enxerga e opera apenas a loja que a gerou.
As consultas estão nas seções a seguir; as ações, em Ações. A lista completa de tipos e campos está na referência do esquema, e há receitas para os casos mais comuns. Para saber o que acontece sem consultar, veja os webhooks.

Autenticação

As chaves são geradas em Reval → Integrações no seu admin da Shopify. Dê a cada chave o nome da ferramenta que vai usá-la («Triple Whale», «Looker») e guarde a chave na hora: ela aparece completa uma única vez. Depois, a lista mostra só o prefixo. Envie a chave em cada request como Bearer token:
Se o seu cliente não permite usar Authorization, o header X-Reval-Api-Key é equivalente.
  • Uma chave revogada para de funcionar na hora. As consultas recebem 401 com o código UNAUTHENTICATED.
  • A Reval guarda apenas um hash da chave. Se você a perder, revogue e gere outra.
  • Você pode ter até 25 chaves ativas por loja, cada uma com um nome de até 60 caracteres. A lista mostra o último uso de cada uma, assim você sabe quais revogar.
  • Ao gerar a chave você escolhe leitura e escrita ou somente leitura. Uma chave somente leitura consulta tudo, mas não executa ações (veja Ações). O tipo não muda depois: revogue e gere outra.
As respostas incluem dados pessoais dos seus clientes (email, endereço, telefone, documento fiscal). Trate as chaves como uma senha: não as coloque em código publicado nem as compartilhe por chat.

Primeira consulta

O endpoint aceita introspecção, então qualquer cliente GraphQL (GraphiQL, Insomnia, Postman, Altair) mostra o esquema completo com a descrição de cada campo. Esta página é o resumo; a referência do esquema tem todos os tipos e campos.
  • Só se aceita POST com um body JSON { "query", "variables", "operationName" }: uma operação por request, sem batching nem GET.
  • O endpoint responde a CORS, então uma ferramenta no navegador pode chamá-lo. Não faça isso a partir do front da sua loja: a chave ficaria exposta a qualquer um que abrir o código-fonte.

O que você pode consultar

Os objetos que existem na Shopify trazem o seu GID da Shopify para cruzar com a Admin API: shopifyOrderId, shopifyCustomerId, shopifyVariantId, shopifyProductId. Os identificadores do Mercado Pago (mercadoPagoPreapprovalId, mercadoPagoPaymentId) servem para conciliar com a sua conta MP; as credenciais nunca são expostas.

Convenções

  • Valores (Money) são strings com duas casas decimais: "185.00". A moeda está no campo currency do mesmo objeto.
  • Datas (DateTime) são ISO-8601 em UTC: "2026-11-02T13:00:00.000Z".
  • Enums vêm em maiúsculas: ACTIVE, PAUSED, CANCELLED, MONTHS, PERCENT, DYNAMIC_BOX.
  • Os IDs da Reval são opacos; use sempre o que a API devolveu.

Paginação

Todas as listagens são connections no estilo Shopify: você pede first itens e continua com after usando o endCursor da página anterior.
  • nodes é o atalho quando você não precisa do cursor de cada linha.
  • totalCount conta todas as linhas que atendem ao filtro, não só a página.
  • reverse: true inverte a ordem (do mais antigo ao mais novo).
  • As listagens aninhadas (subscription.orders, customer.subscriptions) paginam do mesmo jeito.

Filtros

Cada listagem aceita um filter com os campos mais usados:
Para sincronizar um warehouse de forma incremental, peça subscriptions(filter: { updatedAfter: "<última execução>" }, sortKey: UPDATED_AT, reverse: true) e orders(filter: { createdAfter: "<última execução>" }).

Limites

Os limites existem para que um integrador que consulta muito nunca afete o checkout nem as cobranças. Quando uma consulta os ultrapassa, a resposta diz qual: A profundidade conta objetos do modelo: subscriptions › items › plan › group são quatro níveis. edges, node, nodes e pageInfo não contam. Toda resposta traz os headers X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset (epoch em segundos) para o seu cliente se regular sozinho.

Erros

Os erros seguem o formato GraphQL, com um extensions.code para o seu código decidir:
As regras de negócio das ações (estado inválido, compromisso mínimo, plano arquivado, recusa do Mercado Pago) não são erros: voltam em userErrors com 200. Veja Ações.

Ações

Além de consultar, a API permite operar as assinaturas da sua loja com as mesmas ações que o lojista tem no admin: pausar, retomar, cancelar, pular a próxima entrega, trocar produtos e quantidades, atualizar o endereço e gerar um link para o portal. Também permite montar links de checkout com vários produtos e os dados do cliente já preenchidos, para que um bot feche a venda com um link pronto. São mutations GraphQL no mesmo endpoint. Cada ação tem exatamente os mesmos efeitos que no admin: o Mercado Pago é atualizado primeiro (se recusar, nada muda na Reval), preço e frete são recalculados quando mudam, os mesmos eventos disparam para Klaviyo, Flow e seus webhooks, e o histórico da assinatura mostra «API (nome da chave)» como autor.

Chaves somente leitura

Ao gerar uma chave em Reval → Integrações você escolhe leitura e escrita ou somente leitura. Uma chave somente leitura executa qualquer consulta, mas toda mutation recebe 403 com o código FORBIDDEN_READ_ONLY. Use-a para dashboards e relatórios; reserve as de escrita para as automações que realmente agem.

Idempotência

As ações movem cobranças e envios reais, então uma nova tentativa (timeout, queda do seu worker) não pode repeti-las. Envie um header Idempotency-Key com um identificador único por operação (um UUID). Se a mesma chave chegar de novo com o mesmo body em até 24 horas, a API devolve a resposta original sem executar nada e marca o header Idempotency-Replayed: true. Se chegar com outro body, responde 422 com IDEMPOTENCY_KEY_REUSED: é um bug do seu lado, não uma segunda operação.
O header é opcional, mas sem ele uma nova tentativa pode pular dois ciclos ou cancelar duas vezes.

Erros de negócio: userErrors

Uma mutation nunca falha com um erro GraphQL por uma regra de negócio. Ela responde 200 com um payload que traz o objeto ou uma lista userErrors com um code para o seu código decidir, e a assinatura fica como estava:

Mutations disponíveis

Todas devolvem { subscription, userErrors }, exceto subscriptionPortalLink e checkoutLinkCreate, que devolvem { url, expiresAt, userErrors }. Pausar a partir de um bot de suporte
Cancelar com motivo e nota
Trocar produtos
Link para o portal em um e-mail de retenção

Exemplos

Assinaturas ativas com seus produtos e a próxima cobrança
Um cliente com todo o histórico
Cancelamentos do mês, com motivo
Planos e caixas publicados