Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.appstle.com/llms.txt

Use this file to discover all available pages before exploring further.

Answers to the questions developers most commonly ask when integrating with Appstle Subscriptions.

​
Widget & storefront

No. You do not need any Appstle API to display subscription options on product pages or add subscriptions to cart.All selling plan data is already available in Shopify’s native product JSON. When you create subscription plans in the Appstle admin, Shopify automatically includes them in the product data on every product page.Read selling plans from the product JSON endpoint:
fetch('/products/your-product-handle.js')
  .then(response => response.json())
  .then(product => {
    // All selling plans are here
    console.log(product.selling_plan_groups);
  });
Read selling plans in Liquid:
{% for selling_plan_group in product.selling_plan_groups %}
  <h3>{{ selling_plan_group.name }}</h3>
  {% for selling_plan in selling_plan_group.selling_plans %}
    <option value="{{ selling_plan.id }}">{{ selling_plan.name }}</option>
  {% endfor %}
{% endfor %}
Add a subscription to cart:
fetch('/cart/add.js', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    id: variantId,
    quantity: 1,
    selling_plan: sellingPlanId  // From product.selling_plan_groups
  })
});
The Appstle APIs are useful when you need to manage existing subscriptions — not for displaying or creating them at checkout.
Yes. There are four approaches:
  1. CSS overrides — The widget uses classes prefixed with appstle_ that you can target in your theme CSS.
  2. Merchant portal settings — Configure widget text, labels, and layout options directly in the Appstle admin without writing code.
  3. JavaScript hooks — Listen to widget events to add custom behavior when the widget loads, when the customer selects a plan, etc.
  4. Build your own widget — Use Shopify’s native selling_plan_groups product data to build a completely custom widget.
The appstle-subscription.js script is automatically injected into your storefront when the app is installed. It:
  1. Reads the product’s selling_plan_groups from Shopify’s native product JSON
  2. Renders the subscription widget based on your Appstle admin configuration
  3. Handles selling plan selection and cart integration
  4. Dispatches JavaScript events you can hook into
No API calls to Appstle servers are made to display the widget — everything comes from Shopify’s product data.

​
Subscriptions & orders

  1. The customer selects a subscription option and adds the product to cart
  2. At checkout, Shopify creates a subscription contract linked to the selling plan
  3. Appstle manages the recurring billing cycle, sending billing attempts to Shopify at the configured frequency
  4. Shopify processes the payment and creates new orders automatically on each cycle
You can determine this directly from Shopify’s Order API — no Appstle API call needed. Check the sellingPlanAllocation field on each line item.GraphQL query:
{
  order(id: "gid://shopify/Order/ORDER_ID") {
    name
    lineItems(first: 50) {
      edges {
        node {
          title
          quantity
          sellingPlanAllocation {
            sellingPlan {
              id
              name
            }
          }
        }
      }
    }
  }
}
If sellingPlanAllocation is non-null, that line item is a subscription purchase. If it is null, it is a one-time purchase.Subscription line item:
{
  "title": "Premium Coffee Blend",
  "quantity": 1,
  "sellingPlanAllocation": {
    "sellingPlan": {
      "id": "gid://shopify/SellingPlan/123456789",
      "name": "Deliver every 30 days"
    }
  }
}
One-time line item:
{
  "title": "Coffee Mug",
  "quantity": 1,
  "sellingPlanAllocation": null
}
An order can contain both subscription and one-time line items. Always check each line item individually.If you use the Shopify REST Admin API, the equivalent field is selling_plan_allocation on each line item in the Order resource.
Yes. Appstle provides a built-in customer portal that merchants can embed on their store’s account page. Customers can:
  • View active subscriptions
  • Skip upcoming orders
  • Pause or resume subscriptions
  • Swap products or variants
  • Update shipping address
  • Change payment method
  • Cancel subscriptions (subject to the merchant’s configured rules)
The portal is configured in the Appstle admin and powered by the Storefront API. You can also build a fully custom portal using the Storefront API directly.

​
API & integration

Pass your API key in the X-API-Key header on every request:
curl -H "X-API-Key: apst_your-api-key" \
  "https://subscription-admin.appstle.com/api/external/v2/subscription-customers/valid/12345"
Generate API keys in the Appstle admin under Settings → API Key Management. You can create up to 10 keys per store. See the Authentication page for full details.
Yes. Appstle supports real-time webhooks for all major subscription events:
  • Subscription created, updated, activated, paused, cancelled
  • Billing success, failure, skipped
  • Upcoming order notifications
  • Billing interval and next order date changes
Webhooks are powered by Svix and include signature verification, automatic retries, and delivery logs. Configure them in Settings → Webhooks. See the Webhooks page for full setup instructions.
A partner key (X-App-Key) is for companies building a product that integrates with Appstle on behalf of multiple merchants — for example a helpdesk, CRM, AI agent, or automation platform.With a partner key, merchants using your integration do not need their own Appstle API subscription. Your application sends both the merchant’s X-API-Key and your X-App-Key together.If you are just building an integration for a single store you own, you only need a regular API key. See the Authentication page for details on applying for a partner key.
No. The Storefront API runs exclusively through Shopify’s App Proxy and requires a logged-in browser session on your storefront domain. It cannot be called from mobile apps, backend servers, or any environment outside the storefront.For mobile apps, use the Admin API with an X-API-Key header instead.

​
Data & privacy

All data is hosted on AWS (US-West-1, California) infrastructure with industry-standard security:
  • TLS 1.2+ encryption in transit
  • AES-256 encryption at rest (AWS KMS)
  • VPC isolation and private subnets
  • SOC, ISO, and PCI-DSS certified infrastructure
All merchant and customer data associated with your store is deleted from Appstle’s systems upon app uninstallation. Deletion is triggered automatically via Shopify’s app/uninstalled webhook.

​
Still have questions?

Contact support@appstle.com or explore the rest of the documentation:

Integration guide

Full walkthrough for building backend integrations.

Webhooks

Real-time event notifications setup and reference.

JavaScript hooks

Storefront widget events for custom UI and analytics.