Using the API

The API lets your own systems read and change subscriptions without anyone opening the app, and tells you whenever a subscription changes so you do not have to keep asking.


It is useful if you run a headless storefront, sync subscriptions into an ERP or a warehouse system, or want a message in Slack when someone cancels.


While the API is new we switch it on store by store. If Settings > Integrations > API says "Contact support to have the API turned on for this store", message us in live chat and we will turn it on for yours.


Getting a token


Go to Supr Bundles & Subscriptions > Settings > Integrations > API. In the API tokens card:


Give the token a Name describing what will use it, so a leaked one can be traced back, and choose what it may do:


  • Read subscriptions, for a system that only reports.
  • Change subscriptions, for one that pauses, cancels or reschedules.
  • Read webhook endpoints and Manage webhook endpoints, for setting up event notifications from your own code rather than from this page.


Then click Create token.


Give each system its own token, so you can turn one off without touching the rest.


The token is shown once. Copy it straight away. We do not store it, so if you lose it you will need to create a new one. Revoke stops everything using that token immediately.


Calling the API


Send the token as a bearer token:


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


You can list subscriptions, fetch one, and then pause, resume, cancel, skip or unskip an order, change the next billing date or the plan, and add, change or remove the products on it. Every change replies with the subscription as it now stands, so you never have to ask again straight afterwards.


The API is for your own servers to call. Do not put a token in a browser, a mobile app or anything else a customer can see, because anyone who finds it can change your subscriptions.


Retrying safely


If a call times out you cannot tell whether it happened. Send an Idempotency-Key header with a value of your own on anything that changes a subscription, and if you retry with the same key we return the first answer instead of doing it twice:


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"


Keys last a day. Reusing one with a different request is refused rather than answered, so you cannot accidentally get the wrong reply.


How many calls you get


Every store starts on the standard allowance, shown in the Rate limit list when you create a token. If your integration needs more, ask us and we will raise it, and the higher options then appear in that list.


Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Going over gets a 429 with a Retry-After telling you how many seconds to wait.


There is also a limit across all of your store's tokens together, because every call also spends your store's Shopify allowance. If one integration goes wrong, that limit is what stops it slowing down your admin and your storefront.


Event notifications


Rather than asking us for changes, have us tell you. In Supr Bundles & Subscriptions > Settings > Integrations > API, in the Event notifications card, enter a URL, tick the events you want and click Add endpoint. We POST to it whenever one happens, and the body contains the subscription exactly as the API would return it.


Available events include a subscription being created, paused, resumed, cancelled, renewed or failing, its next billing date changing, an order being skipped or unskipped, its products or plan changing, and its payment method or shipping address being updated.


Your URL must use https and be reachable from the internet.


Checking a notification really came from us


When you add an endpoint we show you a signing secret, once. Every delivery carries these headers:


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


The signature is the base64 HMAC SHA256 of the timestamp, a full stop, and the exact body we sent, using your secret. Check it before trusting anything:


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 the whole string we showed you, starting sss_whsec_. Use it as it is, including that prefix.


Use the raw body exactly as it arrived, not a re-encoded version of the parsed JSON, or the signature will not match.


Also reject anything whose timestamp is more than five minutes old. The timestamp is part of what is signed, so this is what stops someone replaying a delivery they captured earlier.


You can rotate an endpoint's secret at any time with New secret on the same page. That changes only that endpoint. Turn off pauses deliveries to an endpoint and Remove deletes it.


When your endpoint is down


A delivery that fails is retried with growing gaps for about a day before we give up on it. If an endpoint refuses 20 times in a row we switch it off and show you why, so a URL you have retired does not keep being retried forever. Clicking Turn on clears that.


Getting help


If something is not behaving, every response carries an X-Request-Id. Quote it to support and we can find that exact call.


Common questions


  • Is there an API for subscriptions?

Yes, this one. It is switched on store by store while it is new, so contact support to turn it on.

  • Do I need the API to change many subscriptions at once, for example move their renewal dates?

Not for a one-off change. In Subscriptions, filter the list, tick the subscriptions and use the Reschedule bulk action. The API is for changes your own systems make regularly.

  • Can another app (for example an affiliate or ERP app) read subscription data?

Shopify only lets the app that created a subscription read it, so other apps cannot see our subscriptions directly. Either connect your system to this API, or have the other app read the order and customer tags the app can add, see Tag settings.

  • I lost my token.

We cannot show it again. Revoke the old one and create a new token.

  • Can I put the token in my storefront theme or a mobile app?

No. Anyone who can see it could change your subscriptions. Call the API from your own server only.

Updated on: 09/30/2026

Was this article helpful?

Share your feedback

Cancel

Thank you!