Usar a API

A API permite que seus próprios sistemas leiam e alterem assinaturas sem que ninguém abra o app, e avisa você sempre que uma assinatura muda, para que você não precise ficar consultando.

Ela é útil se você tem uma loja headless, sincroniza assinaturas com um ERP ou um sistema de estoque, ou quer receber uma mensagem no Slack quando alguém cancelar.

Enquanto a API é nova, nós a ativamos loja por loja. Se em Configurações > Integrações > API aparecer "Fale com o suporte para ativar a API nesta loja", envie uma mensagem no chat e ativaremos na sua.

Como obter um token

Acesse Supr Bundles & Subscriptions > Configurações > Integrações > API. No card Tokens de API:

Dê ao token um Nome que descreva o que vai usá-lo, para que um token vazado possa ser rastreado, e escolha o que ele pode fazer:

• Ler assinaturas, para um sistema que só gera relatórios.
• Alterar assinaturas, para um que pausa, cancela ou reagenda.
• Ler endpoints de webhook e Gerenciar endpoints de webhook, para configurar notificações de eventos a partir do seu próprio código, em vez de por esta página.

Depois, clique em Criar token.

Dê a cada sistema o próprio token, para poder desativar um sem mexer nos demais.

O token é exibido uma única vez. Copie-o imediatamente. Nós não o armazenamos, então, se você o perder, será necessário criar um novo. Revogar interrompe imediatamente tudo o que usa esse token.

Como chamar a API

Envie o token como bearer token:

curl https://subscriptions.super-simple.co/api/v1/subscriptions \
  -H "Authorization: Bearer sss_live_..."

Você pode listar assinaturas, buscar uma e, depois, pausar, retomar, cancelar, pular ou desfazer o pulo de um pedido, alterar a próxima data de cobrança ou a opção de assinatura, e adicionar, alterar ou remover os produtos dela. Cada alteração responde com a assinatura como ela está agora, então você nunca precisa consultar de novo logo em seguida.

A API foi feita para ser chamada pelos seus próprios servidores. Não coloque um token em um navegador, em um app de celular ou em qualquer outro lugar que um cliente possa ver, porque qualquer pessoa que o encontrar poderá alterar suas assinaturas.

Como repetir chamadas com segurança

Se uma chamada expirar, não dá para saber se ela foi executada. Envie um cabeçalho Idempotency-Key com um valor seu em tudo que altera uma assinatura e, se você repetir a chamada com a mesma chave, devolvemos a primeira resposta em vez de executar duas vezes:

curl -X POST https://subscriptions.super-simple.co/api/v1/subscriptions/123/pause \
  -H "Authorization: Bearer sss_live_..." \
  -H "Idempotency-Key: 9f1c2a7e-4b0d-4f2a-9c3e-8a1b2c3d4e5f"

As chaves valem por um dia. Reutilizar uma chave com uma requisição diferente é recusado em vez de respondido, para que você não receba a resposta errada por engano.

Quantas chamadas você pode fazer

Toda loja começa com a cota padrão, exibida na lista Limite de requisições ao criar um token. Se sua integração precisar de mais, fale com a gente e aumentaremos, e as opções maiores passarão a aparecer nessa lista.

Cada resposta traz X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Ao ultrapassar o limite, você recebe um 429 com um Retry-After indicando quantos segundos esperar.

Também existe um limite somado para todos os tokens da sua loja, porque cada chamada também consome a cota da Shopify da sua loja. Se uma integração der errado, esse limite impede que ela deixe seu admin e sua loja virtual lentos.

Notificações de eventos

Em vez de nos pedir as alterações, faça com que nós avisemos você. Em Supr Bundles & Subscriptions > Configurações > Integrações > API, no card Notificações de eventos, informe uma URL, marque os eventos desejados e clique em Adicionar endpoint. Enviamos um POST para ela sempre que um evento acontece, e o corpo contém a assinatura exatamente como a API a retornaria.

Os eventos disponíveis incluem uma assinatura ser criada, pausada, retomada, cancelada, renovada ou falhar, a próxima data de cobrança mudar, um pedido ser pulado ou ter o pulo desfeito, os produtos ou a opção de assinatura mudarem, e a forma de pagamento ou o endereço de entrega serem atualizados.

Sua URL precisa usar https e estar acessível pela internet.

Como conferir se uma notificação realmente veio de nós

Quando você adiciona um endpoint, mostramos um segredo de assinatura, uma única vez. Cada entrega traz estes cabeçalhos:

X-SSS-Topic: subscription.paused
X-SSS-Shop-Domain: your-store.myshopify.com
X-SSS-Timestamp: 1758300000
X-SSS-Hmac-SHA256: <signature>

A assinatura é o HMAC SHA256 em base64 do timestamp, um ponto final e o corpo exato que enviamos, usando o seu segredo. Confira-a antes de confiar em qualquer coisa:

const crypto = require("crypto");

const expected = crypto
  .createHmac("sha256", YOUR_SECRET)
  .update(`${req.headers["x-sss-timestamp"]}.${rawBody}`)
  .digest("base64");

const ok = crypto.timingSafeEqual(
  Buffer.from(expected),
  Buffer.from(req.headers["x-sss-hmac-sha256"])
);

YOUR_SECRET é a string inteira que mostramos, começando com sss_whsec_. Use-a exatamente como está, incluindo esse prefixo.

Use o corpo bruto exatamente como chegou, e não uma versão recodificada do JSON já interpretado, ou a assinatura não vai bater.

Rejeite também qualquer entrega cujo timestamp tenha mais de cinco minutos. O timestamp faz parte do que é assinado, e é isso que impede que alguém reenvie uma entrega capturada antes.

Você pode renovar o segredo de um endpoint a qualquer momento com Novo segredo na mesma página. Isso altera apenas aquele endpoint. Desativar pausa as entregas para um endpoint e Remover o exclui.

Quando seu endpoint está fora do ar

Uma entrega que falha é repetida com intervalos crescentes por cerca de um dia antes de desistirmos. Se um endpoint recusar 20 vezes seguidas, nós o desativamos e mostramos o motivo, para que uma URL desativada não continue sendo tentada para sempre. Clicar em Ativar limpa isso.

Como obter ajuda

Se algo não estiver funcionando, cada resposta traz um X-Request-Id. Informe-o ao suporte e conseguimos encontrar exatamente aquela chamada.

Perguntas frequentes

• Existe uma API para assinaturas?

Sim, esta. Ela é ativada loja por loja enquanto é nova, então fale com o suporte para ativá-la.

• Preciso da API para alterar muitas assinaturas de uma vez, por exemplo mudar as datas de renovação?

Não para uma alteração pontual. Em Assinaturas, filtre a lista, marque as assinaturas e use a ação em massa Reagendar. A API é para alterações que seus próprios sistemas fazem com regularidade.

• Outro app (por exemplo, de afiliados ou ERP) pode ler os dados das assinaturas?

A Shopify só permite que o app que criou uma assinatura a leia, então outros apps não veem nossas assinaturas diretamente. Conecte seu sistema a esta API ou faça o outro app ler as tags de pedido e de cliente que o app pode adicionar, veja Configurações de tags.

• Perdi meu token.

Não podemos mostrá-lo de novo. Revogue o antigo e crie um novo token.

• Posso colocar o token no tema da loja ou em um app de celular?

Não. Qualquer pessoa que o veja poderia alterar suas assinaturas. Chame a API somente a partir do seu próprio servidor.

Atualizado em: 24/10/2026