Creating an API key
Before you start, check two things:- The store’s plan includes API access. Any plan can open More → 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 Contact 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 Shop Settings → Account Ownership Settings, by adding their user IDs to Authorized 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.
Some Admin API endpoints also need a feature of the store’s Appstle plan, such as Edit subscription prices, Change next order date or Order now. Without it, they return
400. See Plan features some endpoints need.1
Open API Access
Log in to your Appstle admin panel and navigate to More → API Access.
2
Create a new key
Click Create API key, give it a descriptive Name that identifies the integration it belongs to — for example,
Zapier Integration or Mobile App — choose a Permission (see Key permissions), and click Create key.3
Copy the key immediately
The full key value is shown only once. Copy it now and store it in a secure location such as a secrets manager or environment variable store. You cannot retrieve it again after closing this dialog.
4
Add the key to your integration
Set the key as an environment variable in your server environment and read it at runtime. Never hard-code it in source files.
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 subscriptions into an ERP. Use Read & Write for integrations that change subscriptions, such as updating a contract or skipping an order.
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 change data:
/api/external/v2/customer-portal-token/api/external/v2/manage-subscription-linkand/api/external/v2/manage-subscription-link/{customerId}/api/external/v2/subscription-contracts-email-magic-link/api/external/v2/subscription-customers/sync-info/{customerId}/api/external/v2/associate-shopify-customer-to-external-payment-gateways/api/external/v2/theme-settings/regenerate-scripts-for-shop
Sending the API key
Include the key in theX-API-Key request header on every Admin API call:
curl
api_key query parameter (see Deprecated query parameter).
Keys you create in the app start with apst_. Every store also has one key the app created for it, shown under Legacy API Key. It authenticates the same way, with the 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 same 401 as any wrong key. 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. Requests that send them get the same 401 as any wrong key. 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).
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:
Managing keys
From More → API Access you can:Each store can have up to 10 active API keys. If you need to create an 11th key, revoke an unused existing key first.
Plan features some endpoints need
Besides API access, some Admin API endpoints need a feature of the store’s Appstle plan. When the plan doesn’t include it, the call returns400 for every key, scoped partner tokens included. The message asks the merchant to upgrade and stays the same until the plan changes, so don’t retry.
- Edit subscription prices.
errorKeypermissionDenied,messageUserGeneratedError:Upgrade your plan to modify contract price.PUT /api/external/v2/subscription-contracts-update-line-item-pricePUT /api/external/v2/subscription-contracts-update-line-item-pricing-policyPUT /api/external/v2/subscription-contracts-update-line-item, even when you change only the quantity, variant or selling planPUT /api/external/v2/subscription-contracts-apply-discountPUT /api/external/v2/subscription-contracts-add-discountPUT /api/external/v2/subscription-contracts-remove-discount
- Change billing frequency.
errorKeypermissionDenied,messageUserGeneratedError:Upgrade your plan to modify billing interval.PUT /api/external/v2/subscription-contracts-update-billing-intervalPUT /api/external/v2/subscription-contracts-update-delivery-intervalPUT /api/external/v2/subscription-contracts-update-frequency-by-selling-planPUT /api/external/v2/subscription-contracts-update-frequency-by-compatible-planPUT /api/external/v2/bulk-automations/billing-interval
- Change next order date.
errorKeypermissionDenied,messageUserGeneratedError:Upgrade your plan to modify next billing date.PUT /api/external/v2/subscription-contracts-update-billing-datePUT /api/external/v2/subscription-billing-attempts/reschedule-order/{id}
- Order now.
errorKeyfeature_access_denied,messageUserGeneratedError:You don't have permission to place immediate orders. Please upgrade your plan to enable this feature.PUT /api/external/v2/subscription-billing-attempts/attempt-billing/{id}
- Create subscriptions manually.
errorKeyfeature_access_denied,messageUserGeneratedError:You don't have permission to create manual subscriptions. Please upgrade your plan to enable this feature.POST /api/external/v2/subscription-contract-details/create-subscription-contract. This call has more requirements than the plan: Create a new subscription contract lists them and the400each one returns.
- Subscriber loyalty rewards.
errorKeyloyaltyRewardsNotIncluded,messageUserGeneratedError:Your current plan doesn't include subscription rewards. Upgrade your plan to add or change rewards.POST /api/external/v2/subscription-groups, when a plan in the body has rewards inappstleCycles[]PUT /api/external/v2/subscription-groups, when a new plan in the body has rewards inappstleCycles[]
GET /api/external/v2/cancellation-managements/{id} returns 200 with cancellationType CANCEL_IMMEDIATELY, pauseType PAUSE_IMMEDIATELY, and null for cancellationReasonsJSON and pauseReasonsJSON, whatever the merchant set up.
Stores that choose a paid plan today get Edit subscription prices, Change billing frequency, Change next order date, Order now, Create subscriptions manually and Subscriber loyalty rewards, and the Free plan doesn’t include any of them. Cancellation management is narrower: the Business plans and above include it, and the Free and Starter plans don’t. A store that chose its plan earlier, or is on a custom plan, may not have them: contact support@appstle.com to check.
The three delivery price endpoints, /api/external/v2/subscription-contracts-update-delivery-price, /api/external/v2/subscription-contracts-update-delivery-price-override and /api/external/v2/subscription-contracts-sync-shipping-price, need no plan feature beyond API access. The Shopify Flow action Update Delivery Price is different: it needs Edit subscription prices (see Shopify Flow).
Authentication errors
Every
401 has the same body whatever the cause, so the response doesn’t tell you which check failed. Only timestamp and path change:
429, not 401 or 403. A call that gets 401 isn’t counted against those limits.
Rate limits
The Admin API sets these limits for each store. Calls made with a partner token count against the store they act for, together with the store’s own API keys.- 600 calls a minute. The store’s Build-a-Box calls, and the Appstle app while the merchant uses it, count against the same 600, 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, so reading subscriptions one at a time is limited to 60 a minute.
- Five write calls in progress at once. The store’s Build-a-Box calls, and the Appstle app while the merchant uses it, share these too. Queue writes on your side and send a few at a time.
429 Too Many Requests with a Retry-After: 30 header. Wait at least that long before you retry, and back off further if the 429 comes back.
Send changes to one subscription one at a time: wait for the response before you send the next change to the same subscription. A change that arrives while another change to that subscription is still running waits for it, and fails with 400 if it waits more than a few seconds.
Rate limits in the integration guide has the full table, each 429 body and how to retry. Customer portal calls have limits of their own: see Rate limits in the storefront guide.
Daily limit on immediate orders
New installs and reinstalls of Appstle Subscriptions get a daily limit on immediate orders: 3 a day for the store, unless support has raised it. The day ends at midnight UTC. 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. These count toward the same daily limit:- Calls to Trigger immediate billing for an order with any of the store’s API keys or partner tokens
- The Shopify Flow action Attempt Billing (see Shopify Flow)
- Order now in the Appstle admin
- Order now in the customer portal, when the customer opened the portal from a sign-in link without signing in to the store (see Give customers their portal)
400 with errorKey immediate_order_daily_limit_exceeded. The message names the limit and the time left:
- Check the order before you call. A call uses one of the day’s immediate orders once it gets past the limit check, even when it then fails for another reason, such as an order that’s already billed or a subscription that isn’t active. A call that the limit refuses doesn’t use one.
- Don’t retry before midnight UTC. Every retry fails with the same message until then, unless support raises the limit.
- 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.
Partner integrations
If you are building a product that connects to Appstle on behalf of multiple merchants — for example a helpdesk, CRM, automation platform, or AI agent — use the Partner Integration Framework. If your application needs to call Appstle’s Admin API, use the framework’s Nonce Handshake connection mode:1
Get your partner credentials
Appstle provides your Partner ID and Partner Secret during onboarding. Store the secret securely.
2
Start the merchant connection
Call the relevant
/api/partner/{partnerId}/... endpoints and authenticate with X-Partner-Secret or the configured HMAC headers.3
Wait for merchant approval
The merchant approves the request under More → Partner Connections in Appstle.
4
Receive the scoped API token
Appstle delivers a merchant-specific
apst_... token to your approval callback.5
Call the Admin API
Send the scoped token as
X-API-Key, exactly like a regular API key. Your Partner Secret is only ever used for /api/partner/... connection calls — never send it to Admin API endpoints.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. An endpoint that needs another plan feature, such as the price change endpoints, still needs it with a partner token.
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/subscriptions/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 and custom CSS. A request sent straight to subscription-admin.appstle.com has no App Proxy signature and gets 401 too.
See the Storefront API reference in the sidebar for the endpoints.
Next steps
Quickstart
Make your first authenticated request and get a customer’s subscriptions with curl.
Admin API integration guide
Manage subscriptions, products, discounts and shipping from your server.
Build your own frontend
Selling plans, the cart and the customer portal from your own UI.
Partner integration
Connect your platform and receive scoped API tokens for merchants.