Skip to main content
Every Admin API request must include an API key. You create keys in the Appstle app, which shows each key’s full value only once. Store it securely as soon as you create it.
API keys are server-side only. Never include them in client-side JavaScript, mobile app source code, public repositories, or any environment where end users could inspect them.

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 401 until 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.
Create one key per integration rather than sharing a single key across systems. This lets you revoke access for one integration without disrupting the others.

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:
It gets the same 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-link and /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
Each key in the API Access list shows a Read only or Read & Write badge. You can’t change a key’s permission after you create it: create a new key with the permission you need, move your integration to it, and revoke the old key. The key shown under Legacy API Key has Read & Write access until the merchant revokes it. A scoped partner token has the permission set for the partner during onboarding (see Token properties).

Sending the API key

Include the key in the X-API-Key request header on every Admin API call:
curl
Five bulk-automation endpoints also need the key in the 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

The api_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:
Five bulk-automation endpoints still require the api_key query parameter. They return 400 when api_key is missing, even if the request sends a valid key in the X-API-Key header:
  • PUT /api/external/v2/bulk-automations/billing-interval
  • PUT /api/external/v2/bulk-automations/delivery-price
  • PUT /api/external/v2/bulk-automations/delivery-method
  • POST /api/external/v2/bulk-automations/hide-subscriptions
  • POST /api/external/v2/bulk-automations/replace-product
Send the key in the api_key query parameter on these five calls, and keep their URLs out of your logs. Every other endpoint in the Admin API reference accepts the header alone.

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 returns 400 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. errorKey permissionDenied, message UserGeneratedError:Upgrade your plan to modify contract price.
    • PUT /api/external/v2/subscription-contracts-update-line-item-price
    • PUT /api/external/v2/subscription-contracts-update-line-item-pricing-policy
    • PUT /api/external/v2/subscription-contracts-update-line-item, even when you change only the quantity, variant or selling plan
    • PUT /api/external/v2/subscription-contracts-apply-discount
    • PUT /api/external/v2/subscription-contracts-add-discount
    • PUT /api/external/v2/subscription-contracts-remove-discount
  • Change billing frequency. errorKey permissionDenied, message UserGeneratedError:Upgrade your plan to modify billing interval.
    • PUT /api/external/v2/subscription-contracts-update-billing-interval
    • PUT /api/external/v2/subscription-contracts-update-delivery-interval
    • PUT /api/external/v2/subscription-contracts-update-frequency-by-selling-plan
    • PUT /api/external/v2/subscription-contracts-update-frequency-by-compatible-plan
    • PUT /api/external/v2/bulk-automations/billing-interval
  • Change next order date. errorKey permissionDenied, message UserGeneratedError:Upgrade your plan to modify next billing date.
    • PUT /api/external/v2/subscription-contracts-update-billing-date
    • PUT /api/external/v2/subscription-billing-attempts/reschedule-order/{id}
  • Order now. errorKey feature_access_denied, message UserGeneratedError: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. errorKey feature_access_denied, message UserGeneratedError: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 the 400 each one returns.
  • Subscriber loyalty rewards. errorKey loyaltyRewardsNotIncluded, message UserGeneratedError: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 in appstleCycles[]
    • PUT /api/external/v2/subscription-groups, when a new plan in the body has rewards in appstleCycles[]
One endpoint changes its answer instead of failing. When the plan doesn’t include Cancellation management, 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:
A call over the rate limits gets 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.
A call over a limit gets 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: When the store has used its immediate orders for the day, Trigger immediate billing for an order returns 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.