Skip to main content
Every Bundles Admin API request must carry a valid API key. Each Shopify store has one API key, which you copy from the Appstle dashboard. The key identifies your store, so you never send the store’s domain with a request.

Getting your API key

Before you start, check that the store’s plan includes API access. The API Key Access page shows the key on every plan, but requests with it return 401 until the store’s Appstle Bundles plan includes the API access add-on. You can add it to any plan: contact support@appstle.com. Scoped partner tokens don’t need it (see Partner integrations).
1

Open API Key Access

Log in to your Appstle admin panel and navigate to Settings → API Key Access. The page is titled API Access Token.
2

Copy the key

Copy the value in the API Key field.
3

Store the key securely

The key stays visible on this page, so treat it like a password. Store it in your secrets manager and use it only in server-side code.
API keys grant access to store data. Never expose them in client-side JavaScript, browser extensions, mobile apps, or public repositories.

Key permissions

A Bundles API key has no permission setting. The Admin API has three endpoints today (bundle-rules, bundle-rules/discount and bundle-rules/bab), and all three only read bundle rules, so no key can change data through the Admin API.

Sending the API key

Include your key in the X-API-Key header on every Admin API request.
The call returns up to 10 of your store’s bundle rules. Don’t add a shop parameter: the key already identifies the store. The Admin API ignores a shop parameter that holds your store’s .myshopify.com domain and returns 403 for any other value (see Authentication errors). To filter bundle rules, use the filter parameters in the API reference, such as status.equals=ACTIVE. The integration guide explains the filter syntax and paging. You can also pass the key as the api_key query parameter, but use the header: URLs end up in logs.
Bundles has one API key per store, and the app has no option to rotate or revoke it. If your key is exposed, contact support@appstle.com.
When a merchant uninstalls the app, Appstle deletes the store’s app data, including this key, and requests that send it get 401. Reinstalling the app issues a new key: copy it from API Key Access and update your integration. A reinstall also starts the store on a new Appstle plan, so the new key gets 401 until that plan includes the API access add-on (see Getting your API key).

Authentication errors

A request that fails authentication returns 401 Unauthorized with Content-Type: application/json:
The body is the same for every cause, so check these in order:
  • Missing key. Send the key in the X-API-Key header on every request.
  • Unknown key. Check the key for typos and stray whitespace. Each Appstle app issues its own keys, so a key from another Appstle app is unknown here. Uninstalling the app deletes the key, so after a reinstall, copy the new key from API Key Access.
  • No API access on the plan. Contact support@appstle.com to add the API access add-on. Scoped partner tokens don’t need it.
  • Revoked partner token. The merchant disconnected your app or uninstalled Appstle Bundles. Start a new connection for that store (see Partner integration).
A shop parameter that holds anything other than your store’s .myshopify.com domain returns 403 Forbidden, even when the key is valid:
To fix it, remove the shop parameter.

Rate limits

The Admin API sets these limits for each store:
  • 600 calls a minute. The Appstle app uses the same 600 while the merchant uses it, so don’t plan to use all of it.
  • 60 calls a minute to one endpoint. Query parameters don’t make a separate endpoint, so every page of bundle-rules counts toward the same 60. Once an endpoint has returned five or more errors (status 400 or higher) in a minute, its 60 drops to 10 for the rest of that minute.
  • 10 calls in progress at once. Wait for a call to return before you start an eleventh. Some of the Appstle app’s own calls, such as its analytics pages, share the same 10 while the merchant uses the app. The service can also turn a call away while it is busy with other stores’ calls, so a 429 can come when fewer than 10 of yours are in progress.
Storefront API calls don’t count toward these limits: they have limits of their own. A request over a per-minute limit returns 429 Too Many Requests with {"error":"Rate limit exceeded. Try again later."}. That response has no Retry-After header, so retry with exponential backoff. A request turned away because too many calls are in progress returns 429 with the header Retry-After: 1 and the body {"error":"Too many requests. Try again later."}. Wait that many seconds, then retry, and wait longer if it happens again. A call turned away this way still counts toward the per-minute limits, so retrying in a tight loop can use them up. Don’t retry a request that fails with 400 or 403: fix it first.

Partner integrations

If you are building a product that integrates with Appstle Bundles on behalf of multiple merchants, use the Partner Integration Framework instead of asking merchants to share their keys. Appstle issues your app a scoped apst_ token for each approved store. Send it as X-API-Key, exactly like a store’s API key. Scoped partner tokens work whether or not the store’s plan includes API access.

Storefront API authentication

The Storefront API doesn’t use API keys, and it isn’t Shopify’s Storefront GraphQL API. It serves the build-a-box and bundle widget endpoints. Call it from the storefront, on the store’s own domain: put /apps in front of each path in the Storefront API reference in the sidebar, for example https://your-store.myshopify.com/apps/bundles/bb/api/build-a-box/single-product. Shopify’s App Proxy signs each request and forwards it to Appstle, so you don’t send a credential yourself. A request sent straight to bundles-admin.appstle.com has no App Proxy signature and gets 401.

Storefront API rate limits

Storefront API calls are limited for each visitor and for the store’s storefront as a whole. A visitor is the signed-in customer, or the IP address the call came from when no customer is signed in. The limits count every call to the store’s Storefront API, whoever makes it. Storefront calls don’t count toward the Admin API’s rate limits. Treat these numbers as the most you should send: Paths that differ only in a numeric ID count as one endpoint. A call over a limit gets 429 Too Many Requests with the body {"error":"Rate limit exceeded. Try again later."}, or {"error":"Too many concurrent mutation requests. Please wait for existing requests to complete."} over the PUT limit. The response has no Retry-After header, so retry with exponential backoff. Don’t retry a call that fails with any other 4xx status: fix it first, because five errors in a minute lower that visitor’s limit for the endpoint to 10. Don’t poll: call an endpoint when the visitor acts, and keep what it returns for as long as the page is open.

Storefront API errors