> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://supr-bundles-and-subscriptions.crisp.help/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# 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**](https://admin.shopify.com/apps/super-subscriptions/app/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:

```js
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](/en-us/article/tag-settings-dex0xq/).
- **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.