- Frictionless merchant onboarding — merchants approve each connection from their Appstle dashboard
- No API paywall — merchants don’t need a paid API plan to use your integration
- Scoped tokens — each merchant gets an isolated API key; revocable at any time
- Automatic cleanup — when a merchant disconnects or uninstalls, access is revoked instantly
How it works
The Partner Integration Framework uses a secure handshake protocol with two flows. In Flow A, your app sends Appstle a nonce. In Flow B, your app callsinitiate-connect, and Appstle sends your app a nonce. Both flows end the same way: the merchant approves the connection in their Appstle dashboard, and your app receives a scoped API token.
Getting started
Step 1: Get onboarded
To get started, reach out to the Appstle team at support@appstle.com with the information below. Our team will set up your partner account and send you your credentials.What you’ll need to provide
API namespaces — what you call vs. what is internal
Three URL namespaces appear in this codebase. As a third-party partner, you only ever call the first one. The others exist for Appstle’s merchant portal and inter-app integrations and are documented here so the surface area is unambiguous:/api/integrations/..., it’s an internal Appstle flow and doesn’t apply to your integration.
What you’ll receive
Once onboarded, you’ll receive three values:Step 1b: Choose your authentication mode
Appstle supports two ways to authenticate partner API calls. Your auth mode is configured during onboarding.Option A: Partner Secret (default)
The simplest approach. Pass your secret in a header with every request:Option B: HMAC-SHA256
A more secure approach where requests are signed with a shared HMAC key. Instead of sending the secret directly, you compute a signature over the request body. HMAC signing works on/disconnect and /status, and on /connect and /initiate-connect in Simple Token Exchange mode. If you use the Nonce Handshake, /connect, /initiate-connect and /verify always take X-Partner-Secret, whichever auth mode you choose.
Headers required:
- Get the current Unix timestamp (seconds, not milliseconds)
- Concatenate the timestamp and the raw JSON request body:
timestamp + body.GET /statushas no body, so sign the timestamp alone. - Compute HMAC-SHA256 of that string using your HMAC key
- Send the hex-encoded result in
X-Partner-Signature
- Partner Secret — simpler to implement, fine for most integrations
- HMAC-SHA256 — signs requests instead of sending your secret, on the endpoints that support it. Recommended for security-sensitive integrations
Step 1c: Choose your connect mode
Appstle supports two ways to establish merchant connections. Your connect mode is configured during onboarding.Option A: Nonce Handshake (default)
The full two-way verification flow described in this guide. Both sides verify each other using a one-time nonce. After the handshake, your app receives an Appstle API key (apst_...) to call Appstle’s External API.
Best for: Partners who want to read/write data in Appstle (subscription contracts, billing attempts, product swaps, etc.)
Option B: Simple Token Exchange
A streamlined flow where your app sends its own access token to Appstle (or you callinitiate-connect, and return your token when Appstle calls your connect endpoint). No nonce, no verify endpoint needed. Appstle stores your token with the connection, but Appstle Subscriptions doesn’t currently call your API or push data with it.
Best for: Connections where your app only needs Appstle to hold a token it issued. Your app can’t call Appstle’s API in this mode, so if you need subscription data, use Nonce Handshake.
Key difference from Nonce Handshake: In Simple Token Exchange, your app provides its own access token to Appstle and does not receive an Appstle API key. Appstle Subscriptions doesn’t currently push data to partner apps, so a sync_path isn’t used.
How Simple Token Exchange works:
Started with connect:
access_token is stored securely but will not be activated until the merchant approves the connection from their Appstle dashboard. Once approved, Appstle calls your /appstle/approved endpoint to confirm (see Handling the approval callback).POST /api/partner/{id}/initiate-connect with { "shop_domain": "..." }, authenticated the same way as /connect. Appstle then calls your /appstle/connect endpoint with { "shop_domain": "..." }, and your app answers within 5 seconds with:
success must be the JSON boolean true. Appstle stores your token, and your initiate-connect call returns { "status": "pending_merchant_approval" }. The connection then waits for the merchant’s approval, the same as one started with connect, and Appstle calls your /appstle/approved endpoint when the merchant approves.
If your answer has no "success": true, or no access_token, the call fails with VERIFICATION_FAILED. If Appstle can’t reach your endpoint, or your endpoint answers with a status other than 2xx or takes longer than 5 seconds, it fails with PARTNER_UNREACHABLE.
Step 2: Understand the callback nonce
What is a callback nonce?
A nonce (number used once) is a random, single-use string that proves both sides of the connection are who they claim to be. It prevents replay attacks and ensures the handshake can’t be forged.Requirements
How to generate a nonce
Use your language’s cryptographically secure random number generator.How to store a nonce
Store the nonce temporarily, keyed by shop domain, with a 5-minute expiry. Delete it after verification.Step 3: Implement your endpoints
Your app must expose two HTTP endpoints that Appstle calls during the connection handshake. The paths default to/appstle/connect and /appstle/verify but can be customized during onboarding.
Both endpoints must:
- Accept
POSTrequests with a JSON body - Return JSON responses
- Be accessible over HTTPS (Appstle will not call HTTP endpoints)
- Respond within 5 seconds. After that, Appstle stops waiting and treats the call as failed.
- Be idempotent. Appstle doesn’t retry these calls, but your endpoints can still get more than one call for the same shop: a merchant can disconnect and reconnect quickly, and when you retry a call to Appstle, Appstle can call your endpoint again. Treat every call as an upsert keyed by
(shop_domain, partnerId), never a blind insert. The same rule applies to your/appstle/approvedand/appstle/disconnectendpoints described later.
Endpoint 1: POST /appstle/connect
When is this called? Only in Flow B. When your app calls initiate-connect, Appstle calls this endpoint before it answers you. In Simple Token Exchange mode the body is { "shop_domain": "..." } instead (see Step 1c).
What does it receive?
- Validate the shop — check that this
shop_domainexists in your system. If you don’t recognize the shop, return an error. - Store the nonce and callback URL — save
callback_nonceandcallback_urlassociated with thisshop_domain. You’ll need them to complete the handshake. - Call back to Appstle — call the
callback_urlto complete the handshake. Appstle then holds the connection until the merchant approves it, and delivers your API token to your/appstle/approvedendpoint. See Completing the handshake below. - Answer within 5 seconds — any
2xxstatus tells Appstle you received the nonce. Any other status, or no answer within 5 seconds, makes yourinitiate-connectcall fail withPARTNER_UNREACHABLE. If you callcallback_urlbefore you answer, as the sample below does, keep the whole handler under 5 seconds.
Endpoint 2: POST /appstle/verify
When is this called? Only in Flow A, while your connect call waits. Appstle is asking your app: “Did you actually send this nonce?”
What does it receive?
- Look up the stored nonce for this
shop_domain - Compare the
callback_noncefrom the request against your stored nonce - If they match: delete the stored nonce (it’s single-use) and return
{ "verified": true } - If they don’t match: return
{ "verified": false }
Step 4: Implement the connect flow (your dashboard)
Now build the merchant-facing “Connect Appstle Subscriptions” button in your app’s dashboard.Your app sends the nonce (Flow A) — step by step
This is the flow where the merchant clicks “Connect Appstle” in your dashboard.Merchant clicks "Connect Appstle" in your dashboard
Your app generates a cryptographically random nonce
shop_domain with a 5-minute TTL.Your app calls POST /api/partner/{id}/connect
shop_domain, the callback_nonce, and your Partner Secret.Appstle validates your Partner Secret
Appstle calls YOUR /appstle/verify endpoint
shop_domain and the same callback_nonce.Your /appstle/verify checks the nonce
{ "verified": true }.Appstle returns pending_merchant_approval
Merchant approves in their Appstle dashboard
Appstle creates a scoped API key
/appstle/approved endpoint.Your app stores the access_token
/appstle/approved endpoint (see Handling the approval callback below). Pending requests expire after 30 days if not acted on.Appstle sends the nonce (Flow B) — step by step
In this flow, your app callsinitiate-connect, and Appstle sends the nonce to your /appstle/connect endpoint. Start it when the merchant asks your app to connect.
Your app calls POST /api/partner/{id}/initiate-connect
shop_domain and your Partner Secret.Appstle checks the request
Appstle generates a nonce (5-min TTL) and calls YOUR /appstle/connect
shop_domain, app, callback_url, and callback_nonce.Your /appstle/connect stores the nonce and callback_url
shop_domain for the verify step.Your app calls the callback_url (Appstle's /verify endpoint)
shop_domain, callback_nonce, and your Partner Secret.Appstle verifies the nonce and records a pending connection
{ "verified": true, "status": "pending_merchant_approval" }. It has no access_token.Merchant approves in their Appstle dashboard
Appstle calls your /appstle/approved endpoint and your app stores the access_token
Starting the handshake (Flow B)
/appstle/connect endpoint answers):
INVALID_REQUEST, TOKEN_INVALID, SHOP_NOT_FOUND, ALREADY_CONNECTED, and PARTNER_UNREACHABLE when your /appstle/connect endpoint can’t be reached, answers with a status other than 2xx, or takes longer than 5 seconds.
Completing the handshake (Flow B)
After your/appstle/connect endpoint receives the nonce and callback URL, your app completes the handshake by calling Appstle’s verify endpoint:
access_token. Appstle creates the API key when the merchant approves the connection, and delivers it to your /appstle/approved endpoint.
Failed response (nonce expired or mismatched):
verify returns 400 with ALREADY_CONNECTED (see Error codes).
Using the API token
After a successful connection, your app has anaccess_token (prefixed with apst_). In both flows, the token is delivered to your /appstle/approved endpoint after the merchant approves (see Handling the approval callback below).
Use this token exactly like a merchant API key — pass it in the X-API-Key header:
Token properties
Available endpoints
Partner tokens grant access to the same External API endpoints as merchant API keys:- Subscription contracts —
GET /api/external/v2/subscription-contract-details - Customer subscriptions —
GET /api/external/v2/subscription-customers/{customerId} - Update subscription status —
PUT /api/external/v2/subscription-contracts-update-status(requires READ_WRITE) - Skip/Reschedule orders —
PUT /api/external/v2/subscription-billing-attempts/skip-order/{id}(requires READ_WRITE) - Delivery address and method —
GET /api/external/v2/subscription-contracts/contract-external/{contractId}(see Read the delivery address and method) - Change the delivery address or method —
PUT /api/external/v2/subscription-contracts-update-shipping-addressorPUT /api/external/v2/subscription-contracts-update-delivery-method(requires READ_WRITE) - Update line items —
PUT /api/external/v2/subscription-contracts-update-line-item(requires READ_WRITE and the Edit subscription prices plan feature) - Apply discounts —
PUT /api/external/v2/subscription-contracts-apply-discount(requires READ_WRITE and the Edit subscription prices plan feature) - And all other
/api/external/v2/*endpoints
Data sync
Appstle Subscriptions doesn’t push data to partner apps, and async_path set during onboarding isn’t used. To keep your platform in sync, poll the External API with the merchant’s apst_ token, or ask the merchant to send webhooks to your endpoint.
Authentication
When Appstle calls your endpoints, it authenticates using the auth mode configured for your partner:- Partner Secret mode: if you gave Appstle an outbound secret during onboarding, every request carries it in the
X-Partner-Secretheader, so check it on each request. Without an outbound secret, requests carry no auth header. - HMAC-SHA256 mode (recommended): Appstle signs every request with
X-Partner-TimestampandX-Partner-Signatureheaders. Your app should verify the HMAC signature to confirm the request came from Appstle.
Disconnecting
Merchant disconnects from Appstle
Merchants can disconnect your integration anytime from More → Partner Connections by clicking Disconnect. When they do:- Your API token for that merchant is revoked immediately
- Subsequent API calls will return
401 Unauthorized - Appstle sends a disconnect webhook to your app (if you configured a
disconnect_pathduring onboarding — see below) - Your app should handle this gracefully and show a “Reconnect” option
401 responses and update your UI to show the connection as disconnected:
Disconnect webhook (first-class endpoint)
Configure adisconnect_path during onboarding, for example /appstle/disconnect. There’s no default: without one, Appstle skips this call. Appstle calls this when the merchant disconnects your app in their Appstle dashboard, rejects your connection request, or uninstalls Appstle entirely. It doesn’t call it when your app disconnects with /disconnect, or when Appstle deactivates your partner account. You should implement this endpoint for every integration — it is the only reliable signal that the merchant has revoked access on Appstle’s side. Polling 401 responses as a fallback works but lags behind.
Request body from Appstle:
X-Partner-Timestamp, X-Partner-Signature) so you can verify it came from Appstle.
Your endpoint must:
- Look up the connection without filtering on status. Don’t
WHERE status = 'active'— if the merchant rapid-clicks disconnect twice, the second call may arrive when the row is already inactive. Find by(shop_domain, partnerId)only. - Revoke the Appstle access token idempotently. If the token is already revoked or absent, return success — don’t error. Revocation must be safe to call repeatedly.
- Mark the local connection inactive. Clear or null out the stored Appstle token so subsequent API calls don’t try to use it.
- Return
2xxeven when there was nothing to do. A no-op disconnect is a successful disconnect from Appstle’s perspective.
401 responses from the Appstle API as a fallback signal that the connection was revoked.Partner disconnects programmatically
Your app can disconnect a merchant using your partner authentication (Partner Secret or HMAC-SHA256):Appstle deactivates your partner account
When Appstle deactivates your partner account, your access ends in every store at once:- Every
apst_token your app holds is revoked. Requests that send one get401 Unauthorized. - Your active connections are disconnected, and your connection requests that are waiting for a merchant’s approval are rejected.
connect,initiate-connect,verify,disconnectandstatusunder/api/partner/{partnerId}/return400with theerrorKeyTOKEN_INVALID, the same as a wrong Partner Secret.
401 on a token that used to work as a disconnected store.
If Appstle activates your account again, each merchant has to approve a new connection, because the old tokens stay revoked. If you authenticate with a Partner Secret, Appstle gives you a new one, and the old secret stops working.
Check connection status
GET /api/partner/{partnerId}/status?shop_domain=... is the authoritative source of truth for whether a merchant is connected. If your UI shows a “Connected” badge, derive it from this endpoint — not from whether you happen to have a stored API key locally.
Partners can authenticate with their Partner Secret or HMAC signature:
Handling the approval callback
When the merchant approves a connection, in either flow, Appstle calls this endpoint on your server.Endpoint: POST /appstle/approved
The path defaults to /appstle/approved but can be customized during onboarding (configured as approval_callback_path).
Request body from Appstle (Nonce Handshake mode):
shop_domain and access_token instead of status, the same body as in Nonce Handshake mode, and the connection becomes active only when your endpoint accepts it.
2xx status within 5 seconds. Appstle ignores the body, so it can be empty, JSON or text. Any other status, or no answer within 5 seconds, fails the approval. See What if the callback fails? below.
If your partner uses HMAC-SHA256 auth, the callback includes signed headers (X-Partner-Timestamp, X-Partner-Signature) so you can verify it came from Appstle.
What if the callback fails?
If your endpoint can’t be reached, doesn’t answer within 5 seconds, or answers with a status other than2xx, the approval fails. Appstle deletes the access token it created for that attempt, leaves the connection pending in Partner Connections, and shows the merchant an error with the key PARTNER_UNREACHABLE that asks them to contact you, then approve again. The merchant’s activity log records why, for example HTTP 401, No response within 5 seconds or Could not connect. Your app never receives a usable token from a failed attempt. After you fix your endpoint, ask the merchant to approve again. Appstle doesn’t retry the callback itself.
This applies whenever Appstle sends your app its access token: in Nonce Handshake mode, and in Simple Token Exchange mode when Appstle issues your app its own access token. In Simple Token Exchange mode without one, the connection becomes active whatever your endpoint answers, so a failed callback only means your app isn’t told. Poll GET /api/partner/{id}/status?shop_domain=... until the status is active.
What if the merchant rejects?
If the merchant clicks “Reject,” the connection status changes torejected and Appstle notifies your app via the disconnect webhook (if configured). Your app should handle this gracefully — show the merchant that the connection was not approved.
Error handling
Partner endpoints return errors in this shape:errorKey. title is a readable message that starts with UserGeneratedError:. GET /status without credentials is the one exception: it returns success, error_code and message instead (see the table).
Error codes
Idempotency requirements — recap
Build every endpoint so that the same call arriving twice leaves the same end state. Concretely:- Connect / approval callbacks: upsert by
(shop_domain, partnerId). When/appstle/approvedarrives again for a shop, replace the stored token with the new one in the same row. A token from a failed approval never works. - Disconnect callback: find the connection without filtering on status; revoke tokens idempotently; return
2xxeven when there is nothing to do. - Status reads: safe by definition — no side effects.
Security checklist
Before going live, verify all of these:- Partner Secret / HMAC Key is stored in environment variables or a secrets manager — not hardcoded in source code
- Nonces are generated using a cryptographically secure random generator (
crypto.randomBytes,secrets.token_hex,SecureRandom, etc.) - Nonces are stored with a TTL (≤ 5 minutes) and deleted after verification
- Nonces are compared using a constant-time comparison to prevent timing attacks (most frameworks do this by default for string equality)
- Endpoints are served over HTTPS — Appstle will not call HTTP endpoints
-
shop_domainis validated in your/appstle/connectand/appstle/verifyendpoints — reject domains you don’t recognize - Access tokens are stored encrypted at rest (or in a secrets manager)
- 401 responses are handled gracefully — show a “Reconnect” option, don’t break silently
- Error responses from Appstle are logged for debugging
- (HMAC only) Server clock is synced via NTP — timestamps more than 5 minutes off will be rejected
- (If using disconnect webhook) Your
/appstle/disconnectendpoint cleans up stored tokens and marks the connection as inactive
Complete example: partner-initiated flow
FAQ
Can a merchant have multiple partner connections?
Can a merchant have multiple partner connections?
What happens if a merchant uninstalls Appstle Subscriptions?
What happens if a merchant uninstalls Appstle Subscriptions?
Can I change my partner's permission level (READ_ONLY vs READ_WRITE) after onboarding?
Can I change my partner's permission level (READ_ONLY vs READ_WRITE) after onboarding?
What's the rate limit for partner API calls?
What's the rate limit for partner API calls?
429 Too Many Requests with a Retry-After header: wait that many seconds before you retry. See Rate limits for the numbers.How do I test the integration before going live?
How do I test the integration before going live?
400 from every endpoint that needs Edit subscription prices, the price endpoints included. Every paid plan you can choose today includes it. Plan features some endpoints need lists those endpoints and every other plan requirement.To choose a paid plan on a development store, first email support@appstle.com with the store’s myshopify.com domain, and choose the plan after Appstle confirms. Appstle sets the store up so that the plan is a Shopify test charge and no real money moves.To test renewals, set up Shopify’s Bogus Gateway, its test payment gateway, and place a test subscription order. Renewals charge that test payment method. To bill an upcoming order on demand, call Trigger immediate billing for an order. It needs the Order now plan feature, which every paid plan you can choose today includes. A new development store also has the daily limit on immediate orders: 3 a day, including calls that then fail for another reason. To test more in one day, ask support@appstle.com to raise the limit for the store.What if the nonce expires before I can complete the handshake?
What if the nonce expires before I can complete the handshake?
connect again. In Flow B, call initiate-connect again, and Appstle sends a new nonce. An expired nonce can’t be used.Do I need to implement both Flow A and Flow B?
Do I need to implement both Flow A and Flow B?
/appstle/verify endpoint, and Flow B needs your /appstle/connect endpoint. Both need your /appstle/approved endpoint, where the API token arrives after the merchant approves.Can I reconnect a merchant without them doing anything?
Can I reconnect a merchant without them doing anything?
Why does every connection require merchant approval?
Why does every connection require merchant approval?
How long does a pending approval last?
How long does a pending approval last?
What happens if the merchant rejects the connection?
What happens if the merchant rejects the connection?
rejected and your app is notified via the disconnect webhook (if configured). The merchant can be asked to reconnect later if they change their mind — your app can initiate a new connection request.Need help?
- Partner onboarding & technical support: support@appstle.com
- Integration guide: Third-party integration guide (for direct API key usage)