# Frequently Asked Questions

## Widget & Storefront

### Do I need the Appstle API to build a custom subscription widget?

**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:**

```javascript
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):**

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

Full Liquid example:

```text
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:

```javascript
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.
:::

### Can I customize the subscription widget appearance?

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](/javascript-hooks) to add custom behavior
4. **Build Your Own** — Use the native Shopify product data (see above) to build a completely custom widget


### How does the widget load on my storefront?

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](/javascript-hooks) 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

### What happens when a customer subscribes?

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


### How do I check if a Shopify order is a subscription order?

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:**

```graphql
{
  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:**

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

**One-time purchase example:**

```json
{
  "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](https://shopify.dev/docs/api/admin-rest/current/resources/order).

### Can customers manage their own subscriptions?

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](/storefront-api-swagger) behind the scenes.

## API & Integration

### How do I authenticate with the Admin API?

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**.

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

See the [Admin API Reference](/admin-api-swagger) for all available endpoints.

### Do you support webhooks?

Yes. Appstle supports [real-time webhooks](/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**.

## Data & Privacy

### Where is my data stored?

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


### What happens to my data if I uninstall the app?

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.