Authentication
Merchant API key
For direct API access, pass the merchant’s API key in theX-API-Key header of every request:
401. Authentication covers key permissions and every authentication error.
Partner integrations
If you are building a product that integrates with Appstle Memberships on behalf of multiple merchants, such as a CRM, helpdesk, email platform or automation tool, use the Partner Integration Framework. Merchants connect your app with one click, and Appstle issues your app a scopedapst_... token for each approved store. Send it as X-API-Key, exactly like a regular API key. It stops working when the merchant disconnects.
To get onboarded, email support@appstle.com with your company name, product description, base URL and contact email.
Base URL
/api/external/v2/.
With a valid API key, a
GET to a path under /api/external/ that has no GET endpoint returns 404, whether the path is mistyped or the endpoint takes another method. A POST, PUT or DELETE to a path that doesn’t take that method returns 405 with Request method 'PUT' not supported (or 'POST', 'DELETE'). If you get either, check the path and the method against the API reference.Find members
List and filter membership contracts
GET /api/external/v2/subscription-contract-details returns the store’s membership contracts as a JSON array. These are the filters integrations use most:
The reference lists every filter. The total number of matching contracts is in the
x-total-count response header, so page until you have read that many.
The
status filter isn’t case-sensitive. The status field in each contract is lowercase ("active"), so compare it without regard to case.Check whether a customer is an active member
Use this before you grant access to gated content or apply member pricing. There are two ways, depending on what you have. You have the customer’s email address. Filter the contract list by email:customerName matches any part of a name or email, so a search for taylor@example.com also returns mtaylor@example.com. Keep only the contracts whose customerEmail equals the address you searched for, ignoring case, then apply the rule in Which contracts count as active.
You have the Shopify customer ID. Get every membership contract of that customer and read status:
Which contracts count as active
A paused or cancelled membership keeps its perks until its next billing date, because the member has paid for that period, unless the store removes them right away. Treat the customer as a member when a contract matches either of these:statusis"active".statusis"paused"or"cancelled",nextBillingDateis in the future, and the store doesn’t remove perks right away in that case.
Stores choose this under More → General Settings → Shop Settings with Immediately revoke customer perks on membership pause and Immediately revoke customer perks on membership cancellation. The API doesn’t return these settings, so ask the merchant which ones are on when you set up the integration. With both on, only
"active" counts.Get one contract
To read one contract in Appstle’s format, filter the list by its ID:subscriptionContractId equals your ID.
To read the raw Shopify contract with its lines, customer, delivery method and billing attempts, call GET /api/external/v2/subscription-contracts/contract-external/{contractId}. There status is Shopify’s own, in uppercase (ACTIVE).
List membership plans
GET /api/external/v2/subscription-groups returns the store’s membership plan groups. Each group has an id, a groupName, the number of products it covers and the customer tag, order tag and member order tag the store applies to its members:
subscriptionPlans empty. To read a group’s plans, call GET /api/external/v2/subscription-groups/{subscriptionGroupId}. Each entry in its subscriptionPlans has an id, such as gid://shopify/SellingPlan/692931264816, and a frequencyName.
To find the plan a contract is on, parse the contract’s contractDetailsJSON. It’s a JSON array encoded as a string, with one entry per line. Each entry’s sellingPlanId and sellingPlanName name the plan, and a sellingPlanId that equals a plan id in a group puts the contract in that group.
Change a membership
Pause or resume a membership
PUT /api/external/v2/subscription-contracts-update-status takes its inputs as query parameters, not a JSON body. status is PAUSED or ACTIVE:
204 No Content with no body. To resume, send the same request with status=ACTIVE. Sending the same request again also returns 204, so it’s safe to retry after a timeout.
The call returns 400 when the contract doesn’t belong to the store (Contract does not exist) or when one of the store’s rules applies:
- The membership hasn’t yet billed its minimum number of cycles and the store holds changes until it has. This applies to a pause and a resume alike. The
errorKeyisminCycleNotCompleteForUpdateSubscriptionContractDate, and the message is the store’s own text for the rule, for exampleUserGeneratedError:Membership requires minimum billing iterations of 3 before it can be cancelled. - You resume a membership that has reached its maximum number of cycles:
UserGeneratedError:Membership completed max cycle. - The store limits changes to a window around the next billing date, for example “This action cannot be performed within 3 days of your next billing date”. The message says how many days.
message and a short code in errorKey. A message that starts with UserGeneratedError: is written for people: remove the prefix and show the rest to the customer or support agent.
Cancel a membership
DELETE /api/external/v2/subscription-contracts/{id} cancels the membership. The optional cancellationFeedback query parameter stores the reason:
204 No Content and cancels the contract in Shopify. The customer gets the store’s cancellation email only while the Membership Canceled email is Active under More → Email Settings → Email Templates in the Memberships app. When it’s Inactive, the call still cancels the membership and returns 204, and no email goes out. A 204 doesn’t tell you whether an email was sent.
There’s no request parameter to suppress the email. To send your own message instead, set Membership Canceled to Inactive and act on the membership.cancelled webhook. That turns the email off for every cancellation in the store, including ones from the customer portal and the merchant admin.
Sending the same cancel again also returns 204, and the customer gets the cancellation email again while it’s Active. After a timeout, read the contract’s status before you retry, and don’t send the cancel again if it’s already "cancelled".
The call returns 400 for a contract that doesn’t belong to the store (Contract does not exist). It is also refused while the membership hasn’t billed its minimum number of cycles, unless the customer is still on a free trial. The message is the store’s own text with the minimum filled in, for example UserGeneratedError:Membership requires minimum billing iterations of 3 before it can be cancelled.
A Read only key can call every
GET in this guide. Pause, resume and cancel need a Read & Write key. A Read only key gets 403 with This API key is read-only and cannot perform write operations.Common integration patterns
CRM / Helpdesk (Gorgias, Zendesk, HubSpot)
CRM / Helpdesk (Gorgias, Zendesk, HubSpot)
Help agents verify and manage memberships directly while handling support tickets:
- Look up the customer’s contracts with
GET /api/external/v2/subscription-customers-detail/valid/{customerId}from the Shopify customer in the ticket - Show the plan (
sellingPlanNamefromcontractDetailsJSON),status,nextBillingDateandcontractAmountin the agent sidebar - Pause, resume or cancel from the helpdesk with one call each
- Write the action back to the ticket for an audit trail
GET /subscription-customers-detail/valid/{customerId}, PUT /subscription-contracts-update-status, DELETE /subscription-contracts/{id}Email / SMS platform (Klaviyo, Omnisend)
Email / SMS platform (Klaviyo, Omnisend)
Sync membership data for lifecycle automations:
- Use webhooks to receive membership events as they happen
- Enrich customer profiles with plan,
statusand next billing date from the contract list - Trigger flows from the events:
membership.billing-failurestarts an “Update your payment method” sequencemembership.cancelledstarts a win-back offermembership.createdstarts a welcome sequencemembership.expiredstarts a re-engagement campaign
GET /subscription-contract-details, webhook eventsAccess control / gated content
Access control / gated content
Control access to content, pages or products based on active membership:
- When the customer signs in to your site, check membership from your server as shown in Check whether a customer is an active member
- Grant access only when a contract counts as active and its
sellingPlanIdbelongs to the plan group that unlocks the resource - Send non-members to your plan page
- Cache the answer per session. Refresh it when a webhook for that customer arrives (
membership.created,membership.activated,membership.paused,membership.cancelledormembership.expired), and when the cachednextBillingDateof a paused or cancelled membership passes
GET /subscription-customers-detail/valid/{customerId}, GET /subscription-contract-detailsAnalytics / BI tools
Analytics / BI tools
Pull membership data for reporting and revenue projections:
- Page through
GET /subscription-contract-detailswithpageandsizeuntil you have readx-total-countcontracts - Filter by
statusto count active, paused and cancelled members - Use
nextBillingDate,billingPolicyIntervalandcontractAmountfor recurring revenue projections - Combine with webhook events to track churn as it happens
GET /subscription-contract-details (paged), GET /subscription-groups, webhook eventsRate limits
The Admin API returns429 Too Many Requests in two cases:
- Per-minute rate limit. The body is
{"error":"Rate limit exceeded. Try again later."}and there’s noRetry-Afterheader. Retry with exponential backoff, never immediately. Failed requests lower the limit: once an endpoint has returned five error responses for your store within a minute, it accepts far fewer requests for the rest of that minute. - Too many
PUTcalls at once. Send no more than fivePUTcalls at a time for one store. Above that, the body is{"error":"Too many concurrent mutation requests. Please wait for existing requests to complete."}and there’s noRetry-Afterheader. Wait for your otherPUTcalls to finish, then retry with exponential backoff.
Response format
Responses use these HTTP status codes:Next steps
API reference
Every filter and response field of the contract list.
Webhooks
Receive an event when a membership is created, paused, cancelled or renewed.
Authentication
Key permissions, partner tokens and every authentication error.