De API gebruiken

Met de API kunnen je eigen systemen abonnementen lezen en wijzigen zonder dat iemand de app opent, en krijg je een melding zodra een abonnement verandert, zodat je niet steeds hoeft te vragen of er iets is gewijzigd.

Het is handig als je een headless webwinkel hebt, abonnementen synchroniseert met een ERP- of magazijnsysteem, of een bericht in Slack wilt als iemand opzegt.

Zolang de API nieuw is, zetten we hem winkel voor winkel aan. Staat er bij Instellingen > Integraties > API "Neem contact op met support om de API voor deze winkel te laten inschakelen", stuur ons dan een bericht in de livechat, dan zetten we hem voor jou aan.

Een token ophalen

Ga naar Supr Bundles & Subscriptions > Instellingen > Integraties > API. In de kaart API-tokens:

Geef het token een Naam die beschrijft wat het gaat gebruiken, zodat een uitgelekt token kan worden herleid, en kies wat het mag doen:

• Abonnementen lezen, voor een systeem dat alleen rapporteert.
• Abonnementen wijzigen, voor een systeem dat abonnementen pauzeert, opzegt of opnieuw inplant.
• Webhook-endpoints lezen en Webhook-endpoints beheren, om gebeurtenismeldingen vanuit je eigen code in te stellen in plaats van op deze pagina.

Klik daarna op Token maken.

Geef elk systeem een eigen token, zodat je er één kunt uitzetten zonder de rest te raken.

Het token wordt maar één keer getoond. Kopieer het meteen. We slaan het niet op, dus als je het kwijtraakt, moet je een nieuw token maken. Met Intrekken stopt alles wat dat token gebruikt onmiddellijk.

De API aanroepen

Stuur het token mee als bearer-token:

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

Je kunt abonnementen weergeven en één opvragen, en daarna pauzeren, hervatten, opzeggen, een bestelling overslaan of weer terugzetten, de volgende factuurdatum of het abonnement wijzigen, en de producten erin toevoegen, wijzigen of verwijderen. Elke wijziging antwoordt met het abonnement zoals het er nu uitziet, zodat je er daarna niet nogmaals naar hoeft te vragen.

De API is bedoeld om door je eigen servers te worden aangeroepen. Zet een token nooit in een browser, een mobiele app of iets anders wat een klant kan zien, want iedereen die het vindt, kan je abonnementen wijzigen.

Veilig opnieuw proberen

Als een aanroep een time-out krijgt, kun je niet zien of hij is uitgevoerd. Stuur bij alles wat een abonnement wijzigt een Idempotency-Key-header mee met een eigen waarde. Als je het opnieuw probeert met dezelfde sleutel, geven we het eerste antwoord terug in plaats van het twee keer uit te voeren:

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"

Sleutels gelden een dag. Een sleutel hergebruiken met een ander verzoek wordt geweigerd in plaats van beantwoord, zodat je nooit per ongeluk het verkeerde antwoord krijgt.

Hoeveel aanroepen je krijgt

Elke winkel begint met het standaardlimiet, dat je ziet in de lijst Limiet wanneer je een token maakt. Heeft je integratie meer nodig, vraag het ons dan, dan verhogen we het en verschijnen de hogere opties in die lijst.

Elk antwoord bevat X-RateLimit-Limit, X-RateLimit-Remaining en X-RateLimit-Reset. Als je over het limiet gaat, krijg je een 429 met een Retry-After die aangeeft hoeveel seconden je moet wachten.

Daarnaast is er een limiet voor alle tokens van je winkel samen, omdat elke aanroep ook van het Shopify-tegoed van je winkel gebruikmaakt. Als één integratie fout gaat, voorkomt dat limiet dat je beheeromgeving en webwinkel trager worden.

Gebeurtenismeldingen

In plaats van ons naar wijzigingen te vragen, kun je ze ook door ons laten melden. Voer in Supr Bundles & Subscriptions > Instellingen > Integraties > API, in de kaart Gebeurtenismeldingen, een URL in, vink de gewenste gebeurtenissen aan en klik op Endpoint toevoegen. We sturen een POST-verzoek naar die URL zodra er een gebeurtenis plaatsvindt, en de body bevat het abonnement precies zoals de API het zou teruggeven.

Beschikbare gebeurtenissen zijn onder meer dat een abonnement wordt gemaakt, gepauzeerd, hervat, opgezegd, verlengd of mislukt, dat de volgende factuurdatum verandert, dat een bestelling wordt overgeslagen of weer teruggezet, dat de producten of het abonnement veranderen, en dat de betaalmethode of het verzendadres wordt bijgewerkt.

Je URL moet https gebruiken en bereikbaar zijn vanaf internet.

Controleren of een melding echt van ons komt

Wanneer je een endpoint toevoegt, tonen we je eenmalig een ondertekeningsgeheim. Elke levering bevat deze headers:

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

De handtekening is de base64-HMAC-SHA256 van het tijdstempel, een punt en de exacte body die we hebben verstuurd, met jouw geheim als sleutel. Controleer hem voordat je iets vertrouwt:

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 is de volledige tekenreeks die we je hebben getoond, beginnend met sss_whsec_. Gebruik hem zoals hij is, inclusief dat voorvoegsel.

Gebruik de ruwe body precies zoals die is binnengekomen, niet een opnieuw gecodeerde versie van de geparseerde JSON, anders klopt de handtekening niet.

Weiger ook alles waarvan het tijdstempel meer dan vijf minuten oud is. Het tijdstempel maakt deel uit van wat is ondertekend, en daarmee voorkom je dat iemand een eerder onderschepte levering opnieuw afspeelt.

Je kunt het geheim van een endpoint op elk moment vernieuwen met Nieuw geheim op dezelfde pagina. Dat wijzigt alleen dat endpoint. Met Uitzetten pauzeer je de leveringen aan een endpoint en met Verwijderen verwijder je het.

Als je endpoint niet bereikbaar is

Een mislukte levering wordt ongeveer een dag lang opnieuw geprobeerd met steeds grotere tussenpozen voordat we het opgeven. Als een endpoint 20 keer achter elkaar weigert, zetten we het uit en laten we je zien waarom, zodat een URL die je niet meer gebruikt niet eindeloos wordt geprobeerd. Met Aanzetten wis je dat.

Hulp krijgen

Als er iets niet werkt zoals verwacht, bevat elk antwoord een X-Request-Id. Geef die door aan support, dan kunnen we precies die aanroep terugvinden.

Veelgestelde vragen

• Is er een API voor abonnementen?

Ja, deze. Zolang hij nieuw is, zetten we hem winkel voor winkel aan, dus neem contact op met support om hem aan te zetten.

• Heb ik de API nodig om veel abonnementen tegelijk te wijzigen, bijvoorbeeld hun verlengingsdatums te verplaatsen?

Niet voor een eenmalige wijziging. Filter in Abonnementen de lijst, vink de abonnementen aan en gebruik de bulkactie Opnieuw plannen. De API is voor wijzigingen die je eigen systemen regelmatig doorvoeren.

• Kan een andere app (bijvoorbeeld een affiliate- of ERP-app) abonnementsgegevens lezen?

Shopify laat alleen de app die een abonnement heeft gemaakt het lezen, dus andere apps kunnen onze abonnementen niet rechtstreeks zien. Koppel je systeem aan deze API, of laat de andere app de bestel- en klanttags lezen die de app kan toevoegen, zie Tag-instellingen.

• Ik ben mijn token kwijt.

We kunnen het niet opnieuw tonen. Trek het oude token in met Intrekken en maak een nieuw token.

• Kan ik het token in mijn webwinkelthema of een mobiele app zetten?

Nee. Iedereen die het kan zien, kan je abonnementen wijzigen. Roep de API alleen aan vanaf je eigen server.

Bijgewerkt op: 24/10/2026