Usare l'API

L'API permette ai tuoi sistemi di leggere e modificare gli abbonamenti senza che nessuno apra l'app, e ti avvisa ogni volta che un abbonamento cambia, così non devi continuare a chiedere.

È utile se gestisci uno storefront headless, sincronizzi gli abbonamenti con un ERP o un sistema di magazzino, oppure vuoi un messaggio su Slack quando qualcuno annulla.

Finché l'API è nuova la attiviamo negozio per negozio. Se Impostazioni > Integrazioni > API mostra "Contatta l'assistenza per attivare l'API per questo negozio.", scrivici in chat e la attiveremo per il tuo.

Ottenere un token

Vai su Supr Bundles & Subscriptions > Impostazioni > Integrazioni > API. Nella scheda Token API:

Dai al token un Nome che descriva cosa lo userà, così un token trapelato può essere ricondotto alla sua origine, e scegli cosa può fare:

• Leggere gli abbonamenti, per un sistema che produce solo report.
• Modificare gli abbonamenti, per uno che mette in pausa, annulla o riprogramma.
• Leggere gli endpoint webhook e Gestire gli endpoint webhook, per configurare le notifiche di eventi dal tuo codice invece che da questa pagina.

Poi fai clic su Crea token.

Dai a ogni sistema il suo token, così puoi disattivarne uno senza toccare gli altri.

Il token viene mostrato una sola volta. Copialo subito. Non lo conserviamo, quindi se lo perdi dovrai crearne uno nuovo. Revoca blocca immediatamente tutto ciò che usa quel token.

Chiamare l'API

Invia il token come bearer token:

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

Puoi elencare gli abbonamenti, recuperarne uno e poi mettere in pausa, riprendere, annullare, saltare o ripristinare un ordine, cambiare la prossima data di addebito o il piano, e aggiungere, modificare o rimuovere i prodotti dell'abbonamento. Ogni modifica risponde con l'abbonamento nel suo stato attuale, così non devi mai richiederlo subito dopo.

L'API è pensata per essere chiamata dai tuoi server. Non inserire un token in un browser, in un'app mobile o in qualsiasi altra cosa che un cliente possa vedere, perché chiunque lo trovi può modificare i tuoi abbonamenti.

Riprovare in sicurezza

Se una chiamata va in timeout non puoi sapere se è stata eseguita. Invia un header Idempotency-Key con un valore tuo su qualsiasi richiesta che modifica un abbonamento: se riprovi con la stessa chiave, restituiamo la prima risposta invece di eseguire l'operazione due volte:

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"

Le chiavi durano un giorno. Riutilizzarne una con una richiesta diversa viene rifiutato invece che ricevere una risposta, così non puoi ottenere per errore la risposta sbagliata.

Quante chiamate hai a disposizione

Ogni negozio parte con il limite standard, mostrato nell'elenco Limite di frequenza quando crei un token. Se la tua integrazione ha bisogno di più chiamate, chiedicelo e lo aumenteremo: le opzioni più alte compariranno poi in quell'elenco.

Ogni risposta contiene X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Se superi il limite ricevi un 429 con un Retry-After che indica quanti secondi attendere.

C'è anche un limite complessivo su tutti i token del tuo negozio, perché ogni chiamata consuma anche il limite Shopify del negozio. Se un'integrazione va storta, è questo limite che le impedisce di rallentare il tuo pannello di controllo e il tuo storefront.

Notifiche di eventi

Invece di chiederci le modifiche, fatti avvisare da noi. In Supr Bundles & Subscriptions > Impostazioni > Integrazioni > API, nella scheda Notifiche di eventi, inserisci un URL, seleziona gli eventi che ti interessano e fai clic su Aggiungi endpoint. Inviamo una richiesta POST a quell'URL ogni volta che uno di essi si verifica, e il corpo contiene l'abbonamento esattamente come lo restituirebbe l'API.

Tra gli eventi disponibili ci sono la creazione, la messa in pausa, la ripresa, l'annullamento, il rinnovo o il mancato pagamento di un abbonamento, il cambio della sua prossima data di addebito, un ordine saltato o ripristinato, il cambio dei suoi prodotti o del piano, e l'aggiornamento del metodo di pagamento o dell'indirizzo di spedizione.

Il tuo URL deve usare https ed essere raggiungibile da internet.

Verificare che una notifica provenga davvero da noi

Quando aggiungi un endpoint ti mostriamo un segreto di firma, una sola volta. Ogni invio contiene questi header:

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

La firma è l'HMAC SHA256 in base64 del timestamp, seguito da un punto e dal corpo esatto che abbiamo inviato, calcolato con il tuo segreto. Verificala prima di fidarti di qualsiasi cosa:

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 è l'intera stringa che ti abbiamo mostrato, che inizia con sss_whsec_. Usala così com'è, prefisso compreso.

Usa il corpo grezzo esattamente come è arrivato, non una versione ricodificata del JSON analizzato, altrimenti la firma non corrisponderà.

Rifiuta anche tutto ciò che ha un timestamp più vecchio di cinque minuti. Il timestamp fa parte di ciò che viene firmato, quindi è questo che impedisce a qualcuno di riprodurre un invio intercettato in precedenza.

Puoi cambiare in qualsiasi momento il segreto di un endpoint con Nuovo segreto nella stessa pagina. Cambia solo quell'endpoint. Disattiva sospende gli invii a un endpoint e Rimuovi lo elimina.

Quando il tuo endpoint non è raggiungibile

Un invio non riuscito viene ritentato a intervalli crescenti per circa un giorno, poi rinunciamo. Se un endpoint rifiuta 20 volte di fila lo disattiviamo e ti mostriamo il motivo, così un URL che hai dismesso non viene ritentato all'infinito. Fare clic su Attiva lo ripristina.

Ottenere aiuto

Se qualcosa non funziona come dovrebbe, ogni risposta contiene un X-Request-Id. Comunicalo all'assistenza e potremo trovare esattamente quella chiamata.

Domande frequenti

• Esiste un'API per gli abbonamenti?

Sì, è questa. Finché è nuova viene attivata negozio per negozio, quindi contatta l'assistenza per attivarla.

• Mi serve l'API per modificare molti abbonamenti in una volta, ad esempio spostare le date di rinnovo?

Non per una modifica una tantum. In Abbonamenti, filtra l'elenco, seleziona gli abbonamenti e usa l'azione in blocco Riprogramma. L'API è per le modifiche che i tuoi sistemi fanno regolarmente.

• Un'altra app (ad esempio un'app di affiliazione o un ERP) può leggere i dati degli abbonamenti?

Shopify permette di leggere un abbonamento solo all'app che lo ha creato, quindi le altre app non possono vedere direttamente i nostri abbonamenti. Collega il tuo sistema a questa API, oppure fai leggere all'altra app i tag di ordini e clienti che l'app può aggiungere, consulta Impostazioni dei tag.

• Ho perso il mio token.

Non possiamo mostrartelo di nuovo. Revoca quello vecchio e crea un nuovo token.

• Posso inserire il token nel tema del mio storefront o in un'app mobile?

No. Chiunque possa vederlo potrebbe modificare i tuoi abbonamenti. Chiama l'API solo dal tuo server.

Aggiornato il: 24/10/2026