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 return401 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.
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 theX-API-Key header on every Admin API request.
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.
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 returns401 Unauthorized with Content-Type: application/json:
- Missing key. Send the key in the
X-API-Keyheader 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).
shop parameter that holds anything other than your store’s .myshopify.com domain returns 403 Forbidden, even when the key is valid:
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-rulescounts toward the same 60. Once an endpoint has returned five or more errors (status400or 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
429can come when fewer than 10 of yours are in progress.
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 scopedapst_ 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.