Skip to main content
This guide shows how to build a server-side integration with Appstle Memberships: find a store’s members, check whether a customer is an active member before you grant access, list the membership plans, and pause, resume or cancel a membership. It ends with patterns for CRMs, email platforms, access control and analytics. Every request in this guide is an Admin API call from your server. The API key identifies the store, so you never pass a shop domain.

Authentication

Merchant API key

For direct API access, pass the merchant’s API key in the X-API-Key header of every request:
Merchants create and manage API keys in the Appstle admin under More → General Settings → API Access. Each key belongs to a single Shopify store and can be revoked on its own. The store’s Appstle plan must include API access, or every request returns 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. Each merchant approves the connection in their Appstle dashboard, and Appstle then issues your app a scoped apst_... token for that 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

All Admin API endpoints are under /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 response is an array. This one contract is trimmed to the fields most integrations read:
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:
The response is an array of the customer’s contracts, in the same format as the list above. An empty array means the customer has never had a membership. Apply the rule in Which contracts count as active.
Despite its name, valid doesn’t mean active. GET /api/external/v2/subscription-customers-detail/valid/{customerId} returns every contract the customer has, whatever its status. GET /api/external/v2/subscription-customers/valid/{customerId} returns only the contract IDs of those same contracts, so a non-empty array doesn’t prove the customer is an active member. Always read status and nextBillingDate.

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:
  • status is "active".
  • status is "paused" or "cancelled", nextBillingDate is 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:
The filter matches every contract whose ID contains the digits you send, so use the entry whose 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:
The list leaves 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:
A successful call returns 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 doesn’t check the membership’s current status. For a cancelled membership, status=PAUSED and status=ACTIVE return 204 and move it from cancelled to paused or active, in Appstle and in Shopify, and the customer gets the store’s pause or resume email, unless the store has turned that email off. If a cancelled membership’s last billing attempt failed, status=ACTIVE can also charge the customer right away for the cycle they missed, and on some stores the plan’s customer tag comes only once that charge succeeds (see the API changelog). Read status first, and only pause or resume memberships that are "active" or "paused".
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 errorKey is minCycleNotCompleteForUpdateSubscriptionContractDate, and the message is the store’s own text for the rule, for example UserGeneratedError: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.
The error body has the text in 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:
A successful call returns 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

Help agents verify and manage memberships directly while handling support tickets:
  1. Look up the customer’s contracts with GET /api/external/v2/subscription-customers-detail/valid/{customerId} from the Shopify customer in the ticket
  2. Show the plan (sellingPlanName from contractDetailsJSON), status, nextBillingDate and contractAmount in the agent sidebar
  3. Pause, resume or cancel from the helpdesk with one call each
  4. Write the action back to the ticket for an audit trail
Key endpoints: GET /subscription-customers-detail/valid/{customerId}, PUT /subscription-contracts-update-status, DELETE /subscription-contracts/{id}
Sync membership data for lifecycle automations:
  1. Use webhooks to receive membership events as they happen
  2. Enrich customer profiles with plan, status and next billing date from the contract list
  3. Trigger flows from the events:
    • membership.billing-failure starts an “Update your payment method” sequence
    • membership.cancelled starts a win-back offer
    • membership.created starts a welcome sequence
    • membership.expired starts a re-engagement campaign
Key endpoints: GET /subscription-contract-details, webhook events
Control access to content, pages or products based on active membership:
  1. When the customer signs in to your site, check membership from your server as shown in Check whether a customer is an active member
  2. Grant access only when a contract counts as active and its sellingPlanId belongs to the plan group that unlocks the resource
  3. Send non-members to your plan page
  4. Cache the answer per session. Refresh it when a webhook for that customer arrives (membership.created, membership.activated, membership.paused, membership.cancelled or membership.expired), and when the cached nextBillingDate of a paused or cancelled membership passes
Key endpoints: GET /subscription-customers-detail/valid/{customerId}, GET /subscription-contract-details
Pull membership data for reporting and revenue projections:
  1. Page through GET /subscription-contract-details with page and size until you have read x-total-count contracts
  2. Filter by status to count active, paused and cancelled members
  3. Use nextBillingDate, billingPolicyInterval and contractAmount for recurring revenue projections
  4. Combine with webhook events to track churn as it happens
Key endpoints: GET /subscription-contract-details (paged), GET /subscription-groups, webhook events

Rate limits

The Admin API returns 429 Too Many Requests in two cases. Both count your calls together with the calls the Appstle app makes while the merchant uses it, and the write limit also counts the store’s storefront writes:
  • Per-minute rate limit. Each store can make 600 calls a minute, and 60 a minute to any one endpoint. Paths that differ only in a numeric ID count as one endpoint. Over a limit, the body is {"error":"Rate limit exceeded. Try again later."} and there’s no Retry-After header. 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 only 10 calls for the rest of that minute.
  • Too many write calls at once. Send no more than five write calls at a time for one store. Every PUT counts, and so do POST /api/external/v2/delivery-profiles/create-shipping-profile and POST /api/external/v2/delivery-profiles/v2/create-shipping-profile. Above that, the body is {"error":"Too many concurrent mutation requests. Please wait for existing requests to complete."} and there’s no Retry-After header. Wait for your other write calls to finish, then retry with exponential backoff.
To keep the number of calls down, cache each customer’s membership status for the length of their session. Billing an order right away has its own daily limit, which returns 400, not 429: see Daily limit on immediate orders.

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.