This guide covers the Storefront API surface (
/cp/api/...), which is designed for customer-facing storefront code.
If you are building a server-side integration, see the Integration guide instead — it covers the Admin API (/api/external/v2/..., authenticated with X-API-Key).When to build your own vs. use the widget
The Appstle subscription widget (appstle-subscription.js) is injected automatically on your storefront and handles selling-plan rendering, cart integration, and the customer portal out of the box. Build your own frontend when you need:
- A product page UI that doesn’t match what the widget renders (custom layout, framework-specific components, headless storefronts)
- A customer portal that matches your own account page design rather than the default portal
- Programmatic control over subscription flows (e.g. a React/Vue app that manages state itself)
Architecture overview
Appstle’s Storefront APIs are served through Shopify’s App Proxy. When a request hits your shop’s domain at the proxy path, Shopify forwards it to Appstle’s backend with authentication parameters attached./apps/subscriptions. Merchants can customize this in their Shopify admin, but apps/subscriptions is the standard default.
Authentication
The Storefront API does not use API keys. Authentication depends on the context:
A few portal endpoints work without a logged-in customer (portal settings, custom CSS, magic link emails). Everything else — viewing contracts, skipping orders, updating addresses — requires the customer to be authenticated through a Shopify session.
The Storefront API works on every Appstle plan. API access, the plan feature that Admin API keys need, doesn’t apply to it. Some Storefront calls still need another feature of the store’s plan. Without it, they return
400 with the errorKey and message below, for every customer, until the plan changes, so don’t retry. Show the customer that the option isn’t available:
For the Admin API’s list, see Plan features some endpoints need.
Rate limits
Customer portal calls, the ones under/apps/subscriptions/cp/api/, are limited for each signed-in customer. One customer’s calls never use up another customer’s allowance, and these calls don’t count against the store’s Admin API limits. The limits count every call the customer makes under /apps/subscriptions/cp/api/, including the calls the Appstle widget and customer portal make for them. Treat these numbers as the most you should send:
The endpoints that allow 60 calls a minute, and don’t drop after errors, are these under
/apps/subscriptions/cp/api/: storefront-graphql, label-translations/locale, subscription-customers-detail/valid/subscription-list, subscription-contracts-freeze-status-detail, subscription-contract-details/subscription-fulfillments/order/{orderId}, subscription-billing-attempts/top-orders and subscription-contract-details/current-cycle/{contractId}.
Build-a-Box calls, the ones under /apps/subscriptions/bb/api/, aren’t counted per customer. They count against the store’s Admin API limits, together with the Admin API and the Appstle app. The store gets 600 calls a minute and 60 a minute to one endpoint, which drops to 10 once that endpoint has returned five errors in a minute. /apps/subscriptions/bb/api/storefront-graphql allows 240 a minute and doesn’t drop. Five write calls can be in progress at once, such as PUT /apps/subscriptions/bb/api/subscription-bundlings/discount/{token}.
A call without a signed-in customer gets 401 before any limit is counted, except on the few endpoints that work without one (portal settings, custom CSS and magic link emails), which are counted per IP address instead. Paths that differ only in a numeric ID count as one endpoint.
A call over a limit can get 429 Too Many Requests with a Retry-After: 30 header and the body {"error":"Rate limit exceeded. Try again later."}, or {"error":"Too many concurrent mutation requests. Please wait for existing requests to complete."} over the write limit. When the request’s Accept header includes text/html, the body is an HTML error page instead. Wait the Retry-After seconds before you retry. Don’t poll: call an endpoint when the customer acts, and keep what it returns for as long as the page is open.
Login link emails
On each store, Appstle sends at most 10 login link emails an hour to one customer email address (the hour is a clock hour in UTC).GET /apps/subscriptions/cp/api/subscription-contracts-email-magic-link?email=... answers differently on each side of the limit:
- A signed-in customer gets
400with theerrorKeyloginLinkEmailLimitReachedand the messageUserGeneratedError:Too many login link emails were sent to this address this hour. Please try again later.once the address has had 10 emails that hour. Show the message and let the customer try again later. A signed-in customer also gets400when the address isn’t on one of their own subscriptions (invalidCustomer) or the store has turned the email off (sendEmailDisabled). - A visitor who isn’t signed in always gets
200withEmail triggered successfully., whether or not Appstle sent the email. Appstle sends it only when the address has subscriptions, the store hasn’t turned the email off, and fewer than 10 went to the address that hour. Word your confirmation as “If this address has subscriptions, we sent a login link”, and don’t promise that an email is on its way.
GET /api/external/v2/subscription-contracts-email-magic-link doesn’t have this limit.
Errors
A failure on the server comes back as HTTP
400, not 500, and the body keeps the real status, as it does on the Admin API:
status in the body, not only the HTTP code. A mistake in the request can cause a 500 too: the body above came from past-orders/report sent with sort=notAProperty,desc. Check the request against the reference first. If it’s correct, wait a few seconds and send it once more. Before you resend a call that changes a subscription, read the subscription back, because the change may have been saved before the error. Don’t retry in a loop: errors lower the endpoint’s limit for every customer on the store (see Rate limits). If the second try fails too, contact support@appstle.com with the store’s myshopify.com domain, the path and the time of the call.
Product page: rendering selling plans
On product pages, you typically don’t need the Storefront API at all. Shopify’s native Liquid and Product JSON already include the selling plan data that Appstle configures.Getting selling plan data from Shopify Liquid
Every Shopify product with subscription selling plans exposes them in theselling_plan_groups array:
Getting selling plan data from Shopify Product JSON
In theme JavaScript, fetch the product from Shopify’s Ajax API. A visitor doesn’t need to sign in. Use the.js URL, not .json, which returns no selling plan data:
Plans a merchant turned off or limited by customer tags
Shopify lists every selling plan on a product, including plans the merchant turned off in the Appstle app and plans that depend on customer tags. A merchant can turn off a whole plan, with Turn off on the Subscription plans page, or one option inside a plan. Appstle’s widget, the checkout upgrade and Shopify POS then stop offering it, but the selling plan stays on the product.product.selling_plan_groups, /products/{handle}.js and selling_plan_allocations still return it, so a picker built from them keeps offering it.
On a theme page with the Appstle Subscriptions app embed on, Appstle’s widget reads these rules from RS.Config.memberOnlySellingPlansJson. It’s an object keyed by selling plan ID, the same number as plan.id, with an entry for each plan that is turned off or depends on customer tags. Tags are separated by commas:
memberInclusiveTagscontainsappstle-plan-inactive: the plan is turned off. Offer it to no one. Other tags that start withappstle-plan-inactiveare Appstle’s record of the plan’s rule while it’s off, so ignore them.enableMemberInclusiveTagistrue: only signed-in customers can choose the plan, and whenmemberInclusiveTagslists tags, only customers with one of them.enableMemberExclusiveTagistrue: a signed-in customer with one of thememberExclusiveTagscan’t choose the plan.
loadPlanRules from any script on the page, even one that runs before the app embed. It waits until the page is parsed and, on stores that load the rules after the page, until the rules arrive. Without the app embed, or when the rules fail to load, there are no rules, so every plan counts as visible. Pass null for a visitor. For a signed-in customer, pass { tags: [...] } with their tags, which you can print into the page from Liquid, for example {{ customer.tags | json }}.
Checkout refuses a turned-off plan only while the store’s Subscription Validations checkout rule is active: the cart then fails with “This subscription option is no longer available. Remove it from your cart to check out.” Ask the merchant to turn the rule on, with the steps in Before you start of the gift subscriptions guide. The rule doesn’t check customer tags, so a plan limited by tags checks out for any customer whose cart has it.
Getting selling plan data from the Appstle Storefront API
For richer subscription data than Shopify’s native objects provide, use the Appstle endpoints below. They work only for a signed-in customer:variantIds for variant-specific data:
A visitor who isn’t signed in gets
401 from these endpoints. On product pages, use Shopify’s Liquid objects or the product JSON above.Adding a subscription to cart
Adding a subscription item to the Shopify cart uses Shopify’s standard Cart API — you include theselling_plan ID alongside the variant ID. On a theme with the Appstle app embed on, the Appstle widget script can change the selling plan in these requests: read When the Appstle app embed is on before you go live.
Using the Cart AJAX API
Using a form
If you prefer a traditional form submission:A fixed-price Build-a-Box also needs line item properties that carry the customer’s choices. See Build a fixed-price Build-a-Box with a custom UI. A Dynamic Pricing Build-a-Box needs a discount code for its tiers: see Build a Dynamic Pricing Build-a-Box with a custom UI.
A gift plan also needs the recipient’s details as line item properties (
properties in /cart/add.js, properties[...] fields in a form). When the store’s Subscription Validations checkout rule is active, checkout refuses a gift without them. See Sell gift subscriptions from your own storefront.When the Appstle app embed is on
While the Appstle Subscriptions app embed is on in the theme, the widget script (appstle-subscription.js) can change the add-to-cart requests your code sends from a product page. It does this only while the store’s add-to-cart interceptor is on. Appstle turns the interceptor on when a store installs the app, and only Appstle support can turn it off. A headless storefront has no theme, so it never loads the script and this section doesn’t apply to it.
On a product page that has an Appstle selling plan group, the script sets the selling plan in /cart/add requests to the one selected in the Appstle widget. The widget’s selection counts even when you hide the widget:
- If the widget has a plan selected, for example because it selects a subscription by default, an item your code adds as a one-time purchase can go into the cart as a subscription to that plan.
- If the widget is on one-time purchase or isn’t on the page, the script can remove the
selling_planyour code sends, and the item goes into the cart as a one-time purchase. Afetchcall with a JSON body, like the example above, can lose its plan this way.
1
Keep the app embed on
The same script also shows the Appstle widget on your other product pages, adds the customer portal link to the account page, loads a customer portal you embed on a page, and sends the JavaScript events. Leave the embed on and turn off only the interceptor.
2
Ask Appstle support to turn off the interceptor
Before you go live with your own picker, email support@appstle.com with the store’s
myshopify.com domain and ask for the add-to-cart interceptor to be turned off, or ask the merchant to. The interceptor is store-wide, so if the Appstle widget still sells subscriptions on other product pages, test one of those pages in the next step too.3
Test the cart
On each product page your customers will use, add a subscription and a one-time purchase, then read the cart:A subscription line shows its selling plan ID, and a one-time line shows
one-time. If a line doesn’t match what you added, something on the page changed your request.Subscription options on upsell and product cards
Use this pattern when a product appears outside its own page, such as an upsell in the cart, a recommendation block or a card in a collection, and the customer should choose one-time or subscribe on the card. It needs no Appstle API call, and the customer doesn’t have to be signed in.1
Read the product's plans
Fetch the product’s A trimmed response:
.js URL, as in Getting selling plan data from Shopify Product JSON. Each variant lists the plans it can use in selling_plan_allocations, with its price for each plan, so the card can show the subscribe price without a second call. Shopify gives prices as the amount times 100 in every currency, including currencies without cents such as JPY. Here 1800 is $18.00:2
Show the choice
Put a one-time and a subscribe option on the card, and keep the customer’s choice in your own code. When the product or the variant has
requires_selling_plan: true, offer only the subscribe option. Appstle’s widget events don’t fire for a picker you build, as the events section explains.3
Add the item
Send A subscription line in the response carries its plan in
selling_plan only for a subscription. Leave it out for a one-time purchase. To refresh the cart in the same call, add sections (the IDs of the theme sections to render) and sections_url (the page they render for):selling_plan_allocation:4
Refresh the cart on the page
sections holds the rendered HTML of each section you asked for, keyed by its section ID. Replace the cart drawer’s markup with it instead of making a second request. Section IDs come from your theme: the id of a section’s element is shopify-section- followed by the section ID. See Shopify’s Section Rendering API for the details.422 and a message in description:
A response is
{"status": 422, "message": "Cart Error", "description": "…"}.
While the Appstle app embed is on, the widget script can change an add-to-cart request. Add an item from your card, read the cart as described in When the Appstle app embed is on, and check that the line has the plan you sent.
If you don’t need your own markup, Appstle’s cart widget lets customers switch a cart item between one-time and subscription without code from you. It fires the cart widget events. The merchant sets it up on the Cart Widget tab of the widget settings in the Appstle Subscriptions app.
Customer portal: managing subscriptions
Once a customer is logged in, you can call the Storefront API through the App Proxy to build a custom subscription management UI. All of these endpoints are under:You don’t have to build a box editor for a Dynamic Pricing Build-a-Box: Appstle’s customer portal shows the box and, depending on the merchant’s settings, lets the customer change it. See After checkout: the customer portal.
Identifying the logged-in customer
401 if no customer is logged in.
Listing a customer’s subscriptions
Get the full subscription profile (active, paused, and cancelled contracts):Viewing upcoming and past orders
Upcoming orders for a contract:variantList lists the lines of the Shopify order, up to the first 50, with variantId, quantity, title, productTitle, productId, variantTitle, image and swapId. It doesn’t include line item properties. Appstle reads an order’s lines from Shopify once, the first time the order is listed, and keeps that copy:
- An order that Appstle hasn’t read yet comes back with an empty
variantList, and Appstle reads its lines in the background. Call again a few seconds later. - Changes made to the order in Shopify after that first read don’t show in
variantList.
- A Dynamic Pricing box puts each pick on its own line, so
variantListlists the picks. - A fixed-price box is one line, the box’s parent product, so
variantListshows the box, not the picks. When the box’s Sync Child Product Inventory setting is on, the order also gets a line for each pick, without properties, andvariantListcan list those too. The picks are properties of the box’s line,productsand__appstle-bb-variants: see How a fixed-price box is stored. Read them from Shopify, not from Appstle: Shopify’s GraphQL APIs call a line item’s propertiescustomAttributes.
Updating subscription status
Pause, resume, or cancel a subscription:pauseReason, pauseFeedback, pauseDurationCycle.
Skipping and unskipping orders
Managing line items
Add a product:Editing line item properties
Line item properties (Shopify calls them custom attributes) are key-value pairs stored on one subscription line, such as a gift message or a grind choice. To let a customer change them, send the line’s full list of properties:
Read
lineId and the line’s current properties from lines.nodes[] (id and customAttributes) in the contract. On success the call returns 200 and the updated contract, in the same shape. The reference page lists every field.
The call replaces the line’s properties. It doesn’t merge them:
- The line keeps exactly the properties in your list. A property you leave out is removed. To change one, send every property back with your change in it. To remove them all, send
[]. - Appstle’s own properties don’t change. Keys such as
_appstle-bb-id,__appstle-bb-name,_min-cyclesand_appstle-one-time-productkeep their stored values whatever you send, so you can send them back as you read them or leave them out. - A Build-a-Box line’s selection is the exception.
products,__appstle-bb-variantsand_appstle-bb-product-skuchange the box’s contents, and the call checks them against the box’s limits. Leave them out of a properties edit. To change the contents, see Build a fixed-price Build-a-Box with a custom UI. - Each key can appear once. A repeated key returns
400witherrorKeyduplicateAttributeKey.
products. Shopify treats underscore keys as private, and every Appstle key except products starts with one.
This example reads a line’s properties, changes the gift message and keeps the rest:
When the call is refused
A refused call returns400 with Content-Type: application/problem+json. When its message starts with UserGeneratedError:, the text after the prefix is written for the customer: show it, and don’t match on its wording. This is the body for a repeated key:
- The contract isn’t the signed-in customer’s. The message is
Contract does not exist, with no prefix, anderrorKeyisinvalidContract. Check thecontractIdyour code sends. - It’s a gift subscription. The buyer can’t change a gift subscription from the storefront. The message is
This is a gift subscription, so it can't be changed here. Please contact us if anything needs to change., anderrorKeyisgiftBuyerReadOnly. - The store has turned off customer editing. The setting is Customers can edit custom details. The message is
Permission denied, Editing attributes is not allowed, anderrorKeyisenableEditAttributes. It applies only when the properties change: sending a line’s properties back unchanged isn’t refused. A store that never saved the setting allows the change through this call, though Appstle’s own portal doesn’t offer editing until the store turns the setting on. - The store’s window for product changes is closed. The window covers property edits too, except on a paused subscription. The message is
Product modifications cannot be made within 3 days of your next billing dateorProduct modifications can only be made within 7 days of your next billing date, with the store’s own number of days, anderrorKeyisproductOperationTimeRestriction. - The subscription hasn’t reached its minimum number of orders. This applies when the store freezes subscriptions until then, and when the line has a
_min-cyclesproperty. The message is the store’s own freeze message, for exampleSubscription cannot be modified until 3 orders have completed.
401, and a call over a rate limit gets 429: see Rate limits. Save once, when the customer confirms the change, not on every keystroke.
Discounts
Apply a discount code:Updating shipping address
changeShippingAddressFlag is true in Get customer portal settings. Send the address as a JSON body:
200 with the updated contract.
When the method type stays SHIPPING or LOCAL, the subscription keeps the title of its current delivery option. When the type changes, that title isn’t carried over. A PICK_UP request doesn’t keep the title of the current pickup option.
Send countryCode as the two-letter country code and provinceCode as the region’s short code, such as CA or BC. The call ignores country and province.
A refused call returns 400 with Content-Type: application/problem+json. When its message starts with UserGeneratedError:, the text after the prefix is written for the customer: show it. The call is refused when:
- The address is incomplete. Without a valid
countryCode, the message isUserGeneratedError:Choose a valid country for this address.Withoutaddress1, it’sUserGeneratedError:Enter a street address.The other address refusals are the same as on the Admin API: see Update shipping address. - The store doesn’t let customers change their address. The setting is Customers can change their shipping address. The message is
UserGeneratedError:Permission denied, Changing shipping address is not allowed. - The zip code isn’t on the store’s list. When the store limits addresses to some zip codes,
zipmust be inallowToSpecificZipCodeForLocalDeliveryfrom the portal settings forLOCAL, or inallowToSpecificZipCodefor any othermethodType,PICK_UPincluded. The message isUserGeneratedError: That zip code is not allowed. - The contract isn’t the signed-in customer’s. The message is
Contract does not exist, with no prefix, anderrorKeyisinvalidContract. - It’s a gift subscription. The buyer can’t change a gift subscription from the storefront.
errorKeyisgiftBuyerReadOnly.
deliveryPrice or that title. On a prepaid subscription that stays on SHIPPING, the call also changes the shipping address of the order that holds the remaining deliveries, when that order holds only this subscription and the country doesn’t change. Otherwise, the deliveries already paid for still go to the old address until the merchant changes that order.
When the store has Sync customer shipping addresses with store profiles on, Appstle copies a customer’s new default address to their subscriptions. A subscription whose address the customer changed with this call no longer gets those copies.
Changing the delivery method
Customers can move a subscription to another of the store’s delivery methods. You apply a method with a fixed rate by its ID. A method that a carrier calculates has no fixed price, so you list the carrier’s live rates for it and apply the rate the customer picks. Offer the change only whenenableUpdateDeliveryMethod is true in Get customer portal settings. New stores start with it off.
1
List the store's delivery methods
rateProvider.__typename says how it’s priced. DeliveryRateDefinition is a fixed rate, with its price. DeliveryParticipant means a carrier calculates the rate: offer the live rates from step 2 in its place, because a carrier-calculated method applied by its ID keeps the subscription’s old price. On a store that uses Shopify Markets shipping, methodDefinitions is empty and liveRates holds the live rates, in the shape step 2 shows.2
List live rates for carrier-calculated methods
Call this only when a method is The response lists each rate Shopify quotes now:Show each choice’s name and price:
DeliveryParticipant. Each call asks Shopify for a new quote and can take a few seconds, so call it when the customer opens your delivery choice, not when the page loads.rateProvider.price for a method, and amount and currencyCode for a live rate. code is the title when Shopify gives the rate no code. The quote can also hold the store’s fixed rates, so the example leaves out a rate whose name, amount and currencyCode match a method from step 1. The list holds shipping rates only. It’s empty when the subscription is delivered by local delivery or pickup, when Shopify quotes no rate, or when the quote can’t be made. A subscription that uses Appstle Pickup & Delivery for local delivery or pickup gets that app’s rates instead, with deliveryType LOCAL or PICK_UP.Don’t build your list of choices from the live quote alone. It can hold fewer rates than the store’s delivery methods, for example only the cheapest of the store’s fixed rates.
3
Apply the customer's choice
id, or a live rate with carrier-rate=true. Every parameter goes in the query string. The three name parameters are required, even with an id.The call returns
204 with an empty body:When the update is refused
A refused update returns400 with Content-Type: application/problem+json and changes nothing. This is the body when a live rate is no longer quoted, or the name and code you send don’t match a quoted rate:
errorKey. Show the text after UserGeneratedError:, list the rates again and let the customer choose again. A rate is a quote from the moment you listed it, so this can happen whenever time passes between the list and the update.
The update is also refused when:
- The store doesn’t let customers change their delivery method. The setting is Customers can change their delivery method, and
enableUpdateDeliveryMethodisfalse. The message isPermission denied, Updating delivery method is not allowed. - Shopify can’t quote the subscription. The message is
Unable to retrieve delivery details from Shopify. - The method isn’t offered to the customer. Step 1 doesn’t return that
delivery-method-idfor the subscription, for example after its address changed. TheerrorKeyisshippingOptionUnavailable. - The contract isn’t the signed-in customer’s. The message is
Contract does not exist, with no prefix, anderrorKeyisinvalidContract. - It’s a gift subscription. The buyer can’t change a gift subscription from the storefront. The
errorKeyisgiftBuyerReadOnly. - The subscription hasn’t reached its minimum number of orders. This applies when the store freezes subscriptions until then, and when a line has a
_min-cyclesproperty. The message is the store’s own freeze message.
204 and leaves its delivery method and price as they are. A call without a signed-in customer gets 401, and a call over a rate limit gets 429: see Rate limits.
For the full request and response, see Get delivery options for subscription contract, List live carrier-quoted shipping rates for a subscription contract and Update delivery method on a subscription contract.
Changing billing date
Changing frequency
Switch to a compatible selling plan frequency:Updating the payment method
A customer can change how a subscription is paid in two ways. Neither call takes card details, so card numbers never pass through your page or Appstle. Offer them only whenhidePaymentMethodEdit isn’t true in Get customer portal settings. That is the merchant’s Customers can edit their payment method setting. The calls themselves don’t check it.
Start by reading the payment method the subscription uses now, from
customerPaymentMethod in the contract. Its instrument.__typename says what kind it is: CustomerCreditCard, CustomerShopPayAgreement, CustomerPaypalBillingAgreement, or another kind, such as BankAccount, that has only __typename. A card or a Shop Pay agreement also holds lastDigits, expiryMonth and expiryYear, and a card also holds brand and expiresSoon. When customerPaymentMethod is null, the subscription has no payment method, so the update email has nothing to update: offer only a saved payment method.
Switch to a saved payment method
List the signed-in customer’s saved payment methods, let them pick one, then set it on the subscription:allowRevokedMethod=true. Its body is empty when Appstle couldn’t read the methods from Shopify, so check for that before you parse it.
firstDigits, maskedNumber and revocable, and a pageInfo object. This example leaves them out. You don’t page through the list: Appstle has already read every page from Shopify. Each kind of instrument has its own fields. A Shop Pay agreement has name, lastDigits and the expiry, a PayPal agreement has paypalAccountEmail instead of card fields, and other kinds, such as BankAccount, have only __typename. Label each option from the fields its kind has.
200 with an empty body. Read the contract again to confirm: its customerPaymentMethod.id is the paymentMethodId you sent.
Replace a card with the update email
200 with an empty body means Shopify accepted the request to send the email. It doesn’t mean that the customer received the email or updated the card. Tell the customer to check their inbox, and keep showing the old card until the contract changes. The email is Shopify’s Customer payment method update request notification. The merchant edits it in the Shopify admin under Settings → Notifications, and the call takes no email content.
Appstle doesn’t tell your page when the customer finishes. Read the contract again when the customer comes back to your page, and compare customerPaymentMethod with what you showed before. Shopify can replace the card inside the same payment method, so compare the card’s lastDigits, expiryMonth and expiryYear, not only the id. Each call asks Shopify for another email, so send one for each customer request.
When the subscription’s last order failed, Appstle can retry it soon after the customer saves the new card. It does so only when the store has Retry as soon as the customer updates their payment method turned on and the subscription is active. Otherwise the order waits for the store’s next scheduled retry, if one is left.
When a call is refused
A refused call returns400 with Content-Type: application/problem+json and changes nothing. The reason is in message, and title holds the same text. The call is refused when:
- The contract isn’t the signed-in customer’s. The message is
Contract does not exist, with no prefix, anderrorKeyisinvalidContract. Check thecontractIdyour code sends. - It’s a gift subscription. The buyer can’t change a gift subscription from the storefront. The message is
UserGeneratedError:This is a gift subscription, so it can't be changed here. Please contact us if anything needs to change., anderrorKeyisgiftBuyerReadOnly. Show the text after the prefix. - The payment method ID is empty. The message is
UserGeneratedError:Invalid payment method provided. - Shopify refuses the payment method. The message is
UserGeneratedError:followed by Shopify’s reason, for exampleUserGeneratedError:Payment method token is invalidfor an ID that Shopify doesn’t know. List the saved payment methods again and let the customer choose again. - Shopify refuses to send the email. The message is
UserGeneratedError:followed by Shopify’s reason.
401, and a call over a rate limit gets 429: see Rate limits.
For the full request and response, see Get current customer’s saved Shopify payment methods, Set existing Shopify payment method on contract and Trigger payment method re-collection email. A server-side integration uses the Admin API versions of these calls: see Send payment method update email to customer and Update subscription payment method.
Portal settings and styling
To load the merchant’s portal configuration (labels, features, display settings):For the full list of Storefront API endpoints with request/response schemas, see the
Storefront API group in the sidebar.
Embed the customer portal on a page
Use the embed to show Appstle’s own customer portal inside a page of your store, such as/pages/community, instead of rebuilding the portal from the Storefront API. The portal runs inside your page, so the customer stays on it and the address keeps your page’s path.
This embeds the customer portal that Appstle serves through the app proxy. The portal that appears inside Shopify’s own customer account pages is a separate Shopify customer account extension, and you can’t embed it elsewhere.
Add the portal to a page
Add an element with the idAppstleCustomerPortal to the page. On a Shopify page, switch the editor to HTML view (the <> button) and paste:
#, so #/subscriptions/list appears after your page’s path once it loads. It draws only when the hash is empty or one of its own routes, such as #/subscriptions/list. With any other hash, such as #account, the element stays empty. If your page uses the hash for its own tabs or anchors, clear it before the portal starts:
Start the portal from your own code
Callwindow.appstleSubscriptionCustomerPortalInit(selector) when the element has a different id or your code adds it after the page loads. The function may not exist until the widget script has loaded, so when it isn’t there yet, wait for the ReadyToEmbed event:
AppstleSubscription:CustomerPortal:Embedded. If no element matches the selector, the call does nothing and fires no event. Call it once per page view.
Stores that use the Customer Account API
When Enable Customer Account API is on under Shop Settings in the Appstle app, the portal reads subscriptions through Shopify’s Customer Account API. A customer with no current Shopify sign-in for the app is sent to Shopify to sign in, and then back. That is a full page navigation, so your page unloads and loads again. With the setting off, there is no sign-in trip. The setting is off by default. The customer comes back to the page they left, withca_authenticated=true added to the address: /pages/community?ca_authenticated=true#/subscriptions/list. Nothing is mounted yet when the page loads again, so:
- If the element is in the page’s HTML, the portal loads on its own and removes
ca_authenticatedfrom the address once it is running. - If your code adds the element, run your start-up code again. A page that hides the portal behind a tab or a button should open that view when
location.searchcontainsca_authenticatedor the hash starts with#/subscriptions, and then start the portal.
ca_error and the reason in the address instead. The portal shows the message Customer Account API Error with the reason, falls back to its standard API and still lists the subscriptions.
Two things can still take the customer off your page:
- The customer comes back to your page only if its host is the store’s
myshopify.comdomain or the Public Domain shown in Shop Settings,wwwincluded. Appstle sets Public Domain to the store’s primary domain when the app is installed, and only Appstle support can change it: if your page is on another domain, contact support@appstle.com. From any other host, the customer lands on/apps/subscriptions, the main portal address. - Shopify limits how long the sign-in lasts, and the app doesn’t receive a refresh token to renew it in the background. A customer who opens the portal after the sign-in has expired makes the trip again. If the portal must stay on your page on every visit, keep Enable Customer Account API off.
Headless storefronts
A headless storefront, such as a Hydrogen app or your own front end on Shopify’s Storefront API, has no Shopify theme. That means no Appstle app embed, no widget script and no add-to-cart interceptor. You don’t need them: Shopify’s APIs carry the subscription through the cart and checkout, and Appstle creates and manages the subscription after checkout.This section uses Shopify’s own Storefront API with a Storefront access token. That token is public: it can read products and build carts, nothing more. It isn’t the Appstle Admin API key, which must stay on your server. The calls below were run on API version
2026-10 with a token that had the unauthenticated_read_selling_plans, unauthenticated_read_product_listings and unauthenticated_write_checkouts scopes.Read the plans
Ask forsellingPlanGroups on the product and sellingPlanAllocations on each variant. A product that has no plan returns empty lists.
RS.Config, so read Appstle’s rules on your server instead: call Get all selling plans across all subscription groups with your Admin API key, and cache the result. Each plan’s id there is the selling plan’s GID, the same id as in the response above.
Filter the plans with isPlanVisible from Plans a merchant turned off or limited by customer tags. Build each plan’s rule from that response: enableMemberInclusiveTag is the plan’s memberOnly, and enableMemberExclusiveTag is its nonMemberOnly, where null means false. memberInclusiveTags and memberExclusiveTags keep their names. For a signed-in customer, pass the tags on their Shopify customer record.
Add a subscription to the cart
Create the cart with the variant asmerchandiseId and the plan as sellingPlanId. Both are GraphQL IDs:
cartLinesAdd with the cart’s id and the same lines. Leave out sellingPlanId for a one-time purchase. Send customers to checkoutUrl to pay.
A variant of a product with requiresSellingPlan: true can’t go in the cart without a plan. The mutation returns no cart and this error:
What happens at checkout
When the customer pays for a cart with a selling plan, Shopify creates the order and Appstle creates the subscription contract for it within seconds. The contract is the same as one made through a theme. It appears in the Admin API, it sends the usual webhooks, and its next billing date follows the plan. You write no code for this step.Plans with a two-step price
A plan can charge one price for its first orders and a different price after that. Appstle counts the orders of each subscription contract, the checkout order plus every successful renewal. Once a contract has had as many orders as the first step covers, Appstle changes its price for the orders after that. Each contract keeps its own count, so a customer who starts a second subscription on the same plan pays the first price again. To show the steps on your storefront, read the plan’spriceAdjustments: orderCount is the number of orders a step covers, and null means the step always applies. See Shopify’s SellingPlanPriceAdjustment for the fields.
Give customers their portal
Customers manage their subscriptions in Appstle’s customer portal, which Shopify serves through the app proxy at/apps/subscriptions on the store’s myshopify.com domain. The portal page renders inside the store’s theme, so that storefront has to stay open: a storefront password page or a theme that sends every page to your front end also keeps customers out of the portal.
Send customers there with a sign-in link that your server requests with your Admin API key. Never call these endpoints from the browser, where the key would be exposed. A read-only key gets 403 from both.
-
Generate the link. Call Generate customer portal link with the customer’s Shopify ID. The response has
manageSubscriptionLink, which opens the portal signed in as that customer and expires after 2 hours. Its host is the Public Domain in Shop Settings, which Appstle sets to the store’s primary domain when the app is installed. -
Build the link yourself when the store’s primary domain is your headless front end, which doesn’t serve the app proxy. Call Generate customer portal authentication token with
customerId, and put the URL-encoded token on themyshopify.comdomain:https://your-shop.myshopify.com/apps/subscriptions?token=TOKEN. The token also expires after 2 hours. -
Open one subscription. Add
#/subscriptions/{contractId}/detail, with the numeric contract ID, to the end of either link. The portal opens on that subscription, signed in as the customer:Its Go Back button, which the store can rename, leads to the customer’s list of subscriptions. When the store skips that list for customers who have only one subscription, the button isn’t there. A contract ID that isn’t the customer’s opens no subscription.
myshopify.com domain or the Public Domain. See Stores that use the Customer Account API.
Next steps for a headless storefront
- Adding a subscription to cart covers the theme-side Ajax equivalents.
- Webhooks tell your backend when a subscription is created, renewed or changed.
- Integration guide covers the Admin API your server calls.
Using JavaScript widget events
On a theme with the Appstle Subscriptions app embed on, the widget script (appstle-subscription.js) loads even when you build your own UI. It dispatches these events on both document and window. A headless storefront doesn’t load the script, so it gets none of them.
Key events for custom frontends
Which of these events fire depends on which Appstle UI is on the page:
- Subscription widget:
widgetInitialised,SellingPlanSelected,SellingPlanDeSelected,sellingPlanChangedandAddToCartIntentfire only from Appstle’s own widget. None of them fire for a picker you build yourself, so keep its state in your own code. If the Appstle widget is still on the page, even hidden, these events come from it and follow its selection, not your picker’s. - Cart widget:
CartWidget:Updated,SwitchedToSubscriptionandSwitchedToOneTimefire only from Appstle’s cart widget. - Customer portal:
CustomerPortal:ReadyToEmbedfires on every page once the widget script has loaded, andCustomerPortal:Embeddedfires each time the portal is added to an element.
Listening to events in your custom UI
Widget initialization event
Theappstle:subscription-widget:loaded event fires once, on window only, when the widget script has initialized. Its detail.api is the same object as window.AppstleSubscriptionWidget. If your script runs after the widget’s, the event has already fired, so check for the object first:
End-to-end example: custom product page subscription UI
This example shows how to render selling plans, let the customer select one, and add a subscription to cart — all without using the default widget UI.This example uses Shopify’s native product data and Cart API, so it doesn’t need the Appstle widget on the page. On a theme with the Appstle app embed on, the widget script can still change the selling plan this example sends: see When the Appstle app embed is on.
Next steps
Fixed-price Build-a-Box
Add a fixed-price Build-a-Box to the cart and save a customer’s changed selection.
Dynamic Pricing Build-a-Box
Add a customer’s picks to the cart and get the tier discount code for checkout.
Webhooks
Receive real-time events when subscriptions change.
JavaScript hooks
Complete list of widget events you can listen to.
Authentication
Admin API keys and storefront authentication details.
Partner integration
Connect a third-party platform on behalf of multiple merchants.
Integration guide
Server-side Admin API integration for backend developers.