div
h1
🚀 Appstle Subscription API Documentation
p
Build powerful subscription experiences and automate workflows for your Shopify store with our comprehensive, enterprise-grade REST APIs.
## Available APIs

div
div
### 🔧 [External APIs](/external-api-swagger)

Server-Side Production Ready

Server-side API for managing subscriptions, orders, and business operations. Perfect for backend integrations, mobile apps, and automated workflows.

**Authentication:** API Key (X-API-Key header)

**Use Cases:**

- Backend integrations & workflows
- Mobile applications (iOS, Android)
- Admin dashboards & reporting
- Bulk operations & automation


div
### 👥 [Customer Portal APIs](/customer-portal-swagger)

Storefront Production Ready

Customer-facing APIs for subscription self-service via Shopify App Proxy. Enable customers to manage their subscriptions directly from your storefront.

**Authentication:** Customer session (logged-in required)

**Use Cases:**

- Custom subscription portals
- Storefront theme integration
- Customer self-service features
- Subscription management UI


## 📖 Overview

div
The Appstle APIs provide **programmatic access** to manage every aspect of your subscription business. Whether you're building custom integrations, internal dashboards, automated workflows, or enhancing your customer experience, our APIs deliver the power and flexibility you need.

div
div
#### 📦 Subscription Management

Create, update, pause, and cancel subscriptions with full lifecycle control

div
#### 👤 Customer Data

Retrieve and sync customer subscription information in real-time

div
#### 💳 Billing & Payments

Process payments, update billing details, and manage payment methods

div
#### 🛒 Product Catalog

Configure subscription products, pricing, and delivery schedules

div
#### 🚚 Order Fulfillment

Manage subscription order cycles and delivery schedules

div
#### 📊 Reporting & Analytics

Access revenue metrics and comprehensive order history

div
#### 🎁 Loyalty & Rewards

Integrate loyalty programs for earning and redeeming points

div
#### 🎨 Customization

Theme settings, custom CSS, and label translations

## 🎯 Which API Should I Use?

div
div
### 🔧 Use **External APIs** when:

✅ Building server-side integrations or workflows
✅ Managing subscriptions from your backend
✅ Creating admin dashboards or reporting tools
✅ Automating bulk operations
✅ Integrating with other business systems
✅ **Building mobile applications (iOS, Android)**
✅ **Any integration outside your storefront**

div
strong
🔑 Authentication:
 API Key (X-API-Key header)
br
strong
🌍 Access:
 Server-side only

div
### 👥 Use **Customer Portal APIs** when:

✅ Building custom customer-facing interfaces **on your storefront**
✅ Adding subscription controls to your theme
✅ **Leveraging Shopify App Proxy** for seamless integration
✅ Creating self-service subscription management
✅ Customizing the customer portal experience

div
strong
🔑 Authentication:
 Customer session (must be logged in)
br
strong
🌍 Access:
 Storefront only (via App Proxy)

div
strong
⚠️ Important:
 Customer Portal APIs are designed specifically for storefront use via Shopify's App Proxy. If you need to call our APIs from anywhere outside your storefront (such as mobile apps, backend services, or external integrations), you 
strong
must use External APIs
 with proper API key authentication.

## ⚡ Quick Start

div
### 1️⃣ Get Your API Key

Obtain your API key from your Appstle dashboard:

div
1. 🔐 Log in to your **Appstle admin panel**
2. ⚙️ Navigate to **Settings** → **API Keys**
3. ✨ Generate a new API key or copy your existing key
4. 🔒 **Store it securely** - treat it like a password


div
strong
💡 Pro Tip:
 Never expose API keys in client-side code, public repositories, or browser applications. Always use them server-side only.

div
### 2️⃣ Make Your First Request

Test your API key by checking if a customer has active subscriptions:


```bash
curl -X GET \
  "https://subscription-admin.appstle.com/api/external/v2/subscription-customers/valid/12345" \
  -H "X-API-Key: your-api-key-here"
```

div
strong
✅ Success Response (200 OK):

```json
[5234567890, 5234567891]
```

div

  📝 
em
This returns an array of Shopify subscription contract IDs for the customer.
## 🔐 Authentication

div
strong
🔑 All API requests require authentication using your API key.
 Include it in the request header for secure, server-side access.

All API requests require authentication using your API key. Include it in the request header:

**Header-based authentication (Recommended):**


```bash
X-API-Key: your-api-key-here
```

**Example Request:**


```bash
curl -H "X-API-Key: your-api-key-here" \
  https://subscription-admin.appstle.com/api/external/v2/subscription-customers/valid/12345
```

**Query parameter (Deprecated):**


```bash
?api_key=your-api-key-here
```

**Important:** Keep your API keys secure. Never expose them in client-side code or public repositories.

## API Reference

Explore our comprehensive API endpoints. Use the sidebar to navigate between:

- **External APIs** - Admin/server-side operations
- **Customer Portal APIs** - Customer-facing operations


Both API sections are collapsed by default - expand the one you need.

### External APIs

#### Subscription Management

Manage all aspects of subscriptions:

- **Subscription Contracts** - Create, update, pause, and cancel subscriptions
- **Subscription Plans** - Configure pricing, billing frequencies, and discounts
- **Subscription Data** - Retrieve subscription products and customer information


### Customer Management

Customer data and subscription information:

- **Customer Subscriptions** - Customer subscription data and status
- **Subscription Details** - Detailed subscription contract information


### Billing & Payments

Payment processing and order management:

- **Billing Attempts** - Process payments and manage billing cycles
- **Payment Methods** - Update and manage payment instruments
- **Order Management** - Skip, reschedule, and manage subscription orders
- **One-Time Add-Ons** - Add one-off products to upcoming subscription orders


### Product Catalog

Product and variant management:

- **Products & Variants** - Subscription product configuration
- **Product Swaps** - Automatic product replacement and rotation


### Build-a-Box & Bundles

Product bundling and subscription boxes:

- **Bundle Configuration** - Create and manage subscription bundles
- **Build-a-Box** - Custom box builder functionality


### Operations & Settings

Operational features and configuration:

- **Bulk Operations** - Bulk automation and management
- **Delivery & Fulfillment** - Shipping profiles and delivery methods
- **Retention & Cancellation** - Cancellation management and retention strategies
- **Settings & Configuration** - Shop settings and activity logs


### Reporting & Analytics

Order and subscription analytics:

- **Contract Analytics** - Revenue metrics and order counts per subscription
- **Past Orders Report** - Detailed billing history with advanced filtering


### Customization & Theming

Shop appearance and configuration:

- **Theme Settings** - Script regeneration and theme integration
- **Custom CSS** - Custom styling for subscription interfaces


### Customer Portal APIs

Customer-facing subscription management endpoints:

- **Subscription Management** - Update, pause, cancel, and reactivate subscriptions
- **Contract Details** - View and modify subscription contract information
- **Billing & Orders** - Skip orders, update next billing date, manage payment methods
- **Product Management** - Swap products, add/remove items from subscriptions
- **Product Data** - Access product information, selling plans, and pricing
- **Account Integration** - Customer authentication and session management
- **Loyalty & Rewards** - Earn and redeem loyalty points on subscriptions
- **Order Reporting** - Past order history and live order status tracking
- **Customization** - Custom CSS, label translations, and shop-specific styling


**Important:** Customer Portal APIs must be called from your shop's domain with a logged-in customer session. These APIs will not work with API key authentication.

Browse the complete API reference in the sidebar →

## 📋 Response Format

div
All API responses follow **standard HTTP status codes** for easy integration and error handling:

| Status Code | Meaning |
|  --- | --- |
| `200` | Success - Request completed successfully |
| `201` | Created - Resource created successfully |
| `400` | Bad Request - Invalid request parameters |
| `401` | Unauthorized - Invalid or missing API key |
| `403` | Forbidden - API key doesn't have required permissions |
| `404` | Not Found - Resource doesn't exist |
| `429` | Too Many Requests - Rate limit exceeded |
| `500` | Server Error - Something went wrong on our end |


**Error Response Example:**


```json
{
  "error": "Unauthorized",
  "message": "Invalid API key provided",
  "status": 401
}
```

## 🔔 Webhooks

div
### Real-Time Event Notifications

Receive real-time notifications when subscription events occur in your Appstle account. Build reactive, event-driven integrations with automatic retries, signature verification, and detailed delivery logs.

**Powered by [Svix](https://www.svix.com/)** — Enterprise-grade webhook infrastructure.

**Available Events:**

- Subscription lifecycle (created, updated, activated, paused, cancelled)
- Billing events (success, failure, skipped)
- Order notifications (upcoming orders, date changes)


div
strong
📚 
a
View Complete Webhooks Documentation →
## Support

**Need help?** Contact our support team at support@appstle.com

**Ready to start building?** Explore the complete API reference using the navigation menu →

*Last updated: January 2026 | API Version: v2*