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:Authorization, o header X-Reval-Api-Key é equivalente.
- Uma chave revogada para de funcionar na hora. As consultas recebem
401com o códigoUNAUTHENTICATED. - 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.
Primeira consulta
- Só se aceita
POSTcom um body JSON{ "query", "variables", "operationName" }: uma operação por request, sem batching nemGET. - 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 campocurrencydo 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ê pedefirst 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.totalCountconta todas as linhas que atendem ao filtro, não só a página.reverse: trueinverte a ordem (do mais antigo ao mais novo).- As listagens aninhadas (
subscription.orders,customer.subscriptions) paginam do mesmo jeito.
Filtros
Cada listagem aceita umfilter com os campos mais usados:
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 umextensions.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 recebe403 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 headerIdempotency-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.
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