Frequently Asked Questions

No. You do not need any Appstle API to build a subscription widget or display subscription options on your storefront.

All the selling plan data is already available in Shopify's native product JSON. When you create subscription plans in the Appstle merchant portal, Shopify automatically includes them in the product data that's available on every product page.

You can access this data in two ways:

1. 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);
  });

2. From Liquid (in your theme):

<h3>{{ selling_plan_group.name }}</h3>
<option value="{{ selling_plan.id }}">{{ selling_plan.name }}</option>

Full Liquid example:

for selling_plan_group in product.selling_plan_groups
  for selling_plan in selling_plan_group.selling_plans
    <!-- render options here -->
  endfor
endfor

The selling_plan_groups array on any product contains everything you need:

• Selling plan names and IDs
• Delivery/billing frequencies
• Price adjustments (discounts)
• Selling plan allocations per variant

To add a subscription to cart, simply include the selling_plan parameter:

fetch('/cart/add.js', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    id: variantId,           // Shopify variant ID
    quantity: 1,
    selling_plan: sellingPlanId  // From product.selling_plan_groups
  })
});

:::info When DO you need the API? The Appstle Admin and Storefront APIs are useful for:

• Admin API: Backend integrations, managing subscriptions programmatically, bulk operations, custom dashboards
• Storefront API: Customer portal customizations, letting customers manage their subscriptions (skip, pause, swap products, update payment methods)

But for simply displaying subscription options and adding them to cart — Shopify's native product data is all you need. :::

Yes. There are several 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 merchant portal
3. JavaScript Hooks — Listen to widget events to add custom behavior
4. Build Your Own — Use the native Shopify product data (see above) 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 merchant portal 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.

1. Customer selects a subscription option and adds 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

You can determine this directly from Shopify's Order GraphQL response — no Appstle API call needed. Check the sellingPlanAllocation field on each line item.

GraphQL Query:

{
  order(id: "gid://shopify/Order/ORDER_ID") {
    name
    createdAt
    lineItems(first: 50) {
      edges {
        node {
          title
          quantity
          sellingPlanAllocation {
            sellingPlan {
              id
              name
            }
          }
        }
      }
    }
  }
}

How to interpret the response:

• sellingPlanAllocation is non-null → That line item is a subscription purchase
• sellingPlanAllocation is null → That line item is a one-time purchase

Subscription line item example:

{
  "title": "Premium Coffee Blend",
  "quantity": 1,
  "sellingPlanAllocation": {
    "sellingPlan": {
      "id": "gid://shopify/SellingPlan/123456789",
      "name": "Deliver every 30 days"
    }
  }
}

One-time purchase example:

{
  "title": "Coffee Mug",
  "quantity": 1,
  "sellingPlanAllocation": null
}

:::info Mixed Orders An order can contain both subscription and one-time line items. Always check each line item individually rather than assuming the entire order is one type. :::

REST API equivalent: If you're using Shopify's REST Admin API, the same field is available as selling_plan_allocation on each line item in the Order resource.

Yes. Appstle provides a Customer Portal that can be embedded in your 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 (based on your configured rules)

The Customer Portal is configured in the Appstle merchant portal and uses the Storefront APIs behind the scenes.

The Admin API uses an API key passed in the X-API-Key header. You can generate your API key in the Appstle merchant portal under Settings → API.

curl -H "X-API-Key: your-api-key" \
  https://subscription-admin.appstle.com/api/external/subscriptions

See the Admin API Reference for all available endpoints.

Yes. Appstle supports real-time webhooks for subscription lifecycle events including:

• Subscription created, updated, cancelled
• Order created, skipped
• Payment success, failure
• And more

Configure webhooks in the Appstle merchant portal under Settings → Webhooks.

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.