Creating an API key
Before you start, check two things:- The store’s plan includes API access. Any plan can open More → General Settings → API Access and create a key, but requests with a key created in the app return
401until the store’s Appstle plan includes API access. Without it, the API Access page shows an upgrade notice: click Chat with us in that notice to add API access. Scoped partner tokens don’t need it (see Partner integrations). - You can open API Access. The store owner, staff with Full access in Shopify, and staff the owner has authorized can view and create keys. Anyone else sees a message with their user ID instead of the key list. The owner authorizes staff under More → General Settings → Shop Settings → Account Ownership Settings, by adding their user IDs to Allow Export To Escalated User IDs or by checking Authorize All Staff Members. Use the ID exactly as that message shows it. If it differs from the number in the address bar of the staff member’s page in Shopify admin, only the ID in the message works.
1
Open API Access
Log in to your Appstle admin panel and navigate to More → General Settings → API Access.
2
Create a new key
Click Create API key, enter a Key name that identifies the integration — for example,
Klaviyo Integration, Mobile App, or Zapier Workflow — choose a Permission (see Key permissions), and click Create.3
Copy the key immediately
Your new key is displayed only once. Copy it now and store it in a secure location such as an environment variable or a secrets manager. You cannot retrieve the full key value again after leaving this screen.
4
Use the key in your requests
Pass the key in the
X-API-Key header of every Admin API request.Key permissions
The Create API key dialog offers two permissions. Read & Write is selected by default.
Use Read only for reporting and one-way syncs, such as pulling members into a data warehouse. Use Read & Write for integrations that change memberships, such as updating a contract.
A read-only key gets
403 Forbidden on any other method:
403 on these GET endpoints, because they send email, issue customer portal links and tokens, or return a customer’s payment tokens:
/api/external/v2/customer-portal-token/api/external/v2/manage-subscription-link/{customerId}/api/external/v2/subscription-contracts-email-magic-link/api/external/v2/customer-payments/token/{customerId}
Sending the API key
Include your key in theX-API-Key request header:
Deprecated query parameter
Theapi_key query parameter still works, but it’s deprecated because URLs end up in logs. Use the X-API-Key header in new integrations. The deprecated form:
Key format
Keys you create in the app start withapst_:
X-API-Key header. The app shows only its last four characters, so if your integration doesn’t already use it, create an apst_ key instead.
When you revoke the legacy key, it stops working immediately, and requests that send it get the Invalid API key. response described under Authentication errors. You can’t undo the revoke, and the app doesn’t issue a replacement, so move your integration to an apst_ key first.
When a merchant uninstalls the app, Appstle deletes the store’s app data, including the legacy key and every apst_ key. A deleted apst_ key gets the unknown-key response and the deleted legacy key gets Invalid API key., both described under Authentication errors. Reinstalling doesn’t bring them back: the app issues a new legacy key, and your integration needs a new apst_ key. A reinstall also starts the store on a new Appstle plan, so the new key gets 401 until that plan includes API access (see Creating an API key).
Key management
You can create up to 10 active API keys per store. Managing keys from the dashboard gives you fine-grained control over which integrations can access your membership data.Storing keys securely
Store your API key as an environment variable and read it at runtime. Never hardcode it in your source files.Daily limit on immediate orders
An immediate order is a call that bills one of a membership’s orders right away: an upcoming order before its date, or an order whose payment failed. New installs and reinstalls of Appstle Memberships get a daily limit on immediate orders: 3 a day for the store, unless support has raised it. The day ends at midnight UTC. Calls with the store’s API keys and partner tokens, and Attempt Billing on an upcoming or failed order in the Appstle admin, share the same 3. A store that installed earlier may not have the limit, but support can turn it on for any store, so handle the error below on every store. When the store has used them, Trigger immediate billing for an order (PUT /api/external/v2/subscription-billing-attempts/attempt-billing/{id}) returns 400 with errorKey immediate_order_daily_limit_exceeded. The message names the limit and the time left:
- Check before you call. A call counts toward the limit even when it then fails. A call that returns
200uses one of the 3 even when its order later endsSKIPPEDor fails, and so does a second call for an order that’s still being billed, which returns400witherrorKeybillingInProgress. Only a call refused earlier, for example for an unknown order or a membership that isn’t active, doesn’t count. If a call times out, check the order’sstatuswith Get past orders before you send it again. - Don’t retry the same day. Every retry fails with the same message until midnight UTC, and each refused call counts too. If support raises the limit later that day, your refused calls have already used part of it.
- Don’t bill a membership twice within 24 hours. If the membership has another order that was billed, failed or is due within 24 hours before or after your call (3 hours when it bills every day), the call still returns
200, but the order endsSKIPPED. No order is created, and that order isn’t billed on its scheduled date either. Before you call, check the membership’s orders with Get past orders and Get upcoming orders. - Ask for a higher limit. Contact support@appstle.com with the store’s domain and what the integration needs it for. A raised limit goes back to 3 when the merchant reinstalls the app.
Authentication errors
A request that fails authentication returns401 Unauthorized with Content-Type: application/problem+json. This is the body for a key that doesn’t exist:
detail field tells you which check failed:
- Missing key.
detailisAPI key can not be blank.Send the key in theX-API-Keyheader on every request. - Unknown key.
detailisInvalid API key. This key was not recognized. Verify it matches the active key shown under API Access settings.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 every key, so after a reinstall, create a new key. - Revoked key.
detailisThis API key has been revoked. Generate a new key under API Access settings.Create a new key and update your integration. - No API access on the plan.
detailisYou do not have permission to access the External API. Please contact the Appstle Membership Support team.Click Chat with us in the upgrade notice on the API Access page to add API access to the store’s plan. Scoped partner tokens don’t need it. - Unknown or revoked legacy key.
detailisInvalid API key.The key doesn’t start withapst_and isn’t the store’s active legacy key. Create anapst_key.
GET endpoints listed under Key permissions, gets 403 Forbidden instead: use a Read & Write key. If the detail is Shop does not match the authenticated session, a shop value in the request isn’t the key’s store: drop the shop parameter, since your key already identifies the store.
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. Paths that differ only in a numeric ID count as one endpoint.
- Five write calls in progress at once. Every
PUTcounts, the storefront’s included, and so do the twoPOSTcalls that create a shipping profile.
429 Too Many Requests with no Retry-After header, so retry with exponential backoff. Rate limits in the integration guide shows each response and how to retry.
Partner integrations
If you are building a product that integrates with Appstle Memberships on behalf of multiple merchants (a CRM, helpdesk, email platform, or automation tool), use the Partner Integration Framework. There’s no manual key exchange: each merchant approves the connection in their Appstle dashboard, and Appstle then issues your app a scopedapst_... token for that store.
Send the merchant’s scoped token as X-API-Key, exactly like a regular API key. Tokens are revoked automatically when a merchant disconnects or uninstalls Appstle.
To get onboarded, email support@appstle.com with your company name, product description, base URL, and contact email.
Scoped partner tokens work whether or not the store’s plan includes API access, so merchants can use an approved partner integration on any plan. Direct API access without a partner connection requires a plan that 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 customer portal endpoints. Call it from the storefront while the customer is signed in, on the store’s own domain, by default under/apps/memberships/cp/api/. Shopify’s App Proxy forwards each request to Appstle with the signed-in customer’s identity, so you don’t send a credential yourself. A call without a signed-in customer gets 401, except on the few GET endpoints that work without one, such as portal settings. A request sent straight to membership-admin.appstle.com has no App Proxy signature and gets 401 too.
See the Storefront API reference in the sidebar for the endpoints.
Storefront API rate limits
Storefront API calls are limited for each signed-in customer and for the store’s storefront as a whole. The limits count every call to the store’s Storefront API, whoever makes it. Storefront calls don’t count against the Admin API’s 600 calls a minute or 60 to one endpoint, but storefront writes share the store’s five writes in progress. Treat these numbers as the most you should send:
When no customer is signed in, which only a few endpoints such as portal settings allow, calls are counted per IP address instead. 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 poll: call an endpoint when the customer acts, and keep what it returns for as long as the page is open.
Sign-in emails
GET /memberships/cp/api/subscription-contracts-email-magic-link?email=... always answers 200 with Email triggered successfully., whether or not the address belongs to a member, so a visitor can’t find out who is a member. Appstle sends the email only when the address has a membership, the store hasn’t turned that email off, and fewer than 10 sign-in emails went to the address in the current clock hour (UTC). Over the limit Appstle sends nothing and the call still answers 200. Word your confirmation as “If this address has a membership, we sent a sign-in link”, and don’t promise that an email is on its way.
The Admin API’s GET /api/external/v2/subscription-contracts-email-magic-link doesn’t have the hourly limit.
Storefront API errors
Next steps
Quickstart
List the store’s membership contracts and check whether a customer is an active member.
Admin API integration guide
Look up members, check whether a customer is an active member, and pause, resume or cancel memberships from your server.
JavaScript events
Embed the customer portal on your own page and start it from your code.
Partner integration
Connect your platform and receive scoped API tokens for merchants.