# Third-Party Integration Guide

Build integrations with Appstle Subscriptions using our REST API. This guide covers authentication, common workflows, and the key endpoints you'll need.

## Authentication

There are two ways to authenticate with the Appstle API:

### Merchant API Key

For direct API access, pass the merchant's API key in the header:


```
X-API-Key: <merchant-api-key>
```

Merchants create API keys from the Appstle admin dashboard under **Settings → API Key Management**. Each key is scoped to a single Shopify store. Merchants can create multiple named keys (up to 10) and revoke them individually.

> **ℹ️ Note:** Direct API access requires an active API plan. Contact [support@appstle.com](mailto:support@appstle.com) for pricing.


### Partner Integration Key

If you're building a product that integrates with Appstle (e.g., a helpdesk, CRM, or automation platform), you can apply for a **Partner Key**. Partner integrations use two headers:


```
X-API-Key: <merchant-api-key>
X-App-Key: <your-partner-key>
```

- **`X-API-Key`** — The merchant's API key, identifying which store to act on. The merchant generates this in their Appstle dashboard and enters it in your integration settings.
- **`X-App-Key`** — Your partner key, identifying your application. This is provisioned by Appstle and is the same across all merchants using your integration.


**How it works:**

1. You apply for a partner key by contacting [support@appstle.com](mailto:support@appstle.com)
2. Appstle provisions a dedicated `X-App-Key` for your application
3. When a merchant wants to connect, they create a dedicated API key in Appstle (named after your integration) and paste it into your integration settings
4. Your application sends both headers with every API request


> **✅ Benefit:** Partner integrations bypass the paid API plan requirement — merchants don't need an API subscription to use your integration.


> **🔒 Security:** Partner keys are unique to your application. Never share your partner key publicly. Treat it as a secret credential.


## Base URL


```
https://subscription-admin.appstle.com
```

All endpoints are prefixed with `/api/external/v2/`.

## Quick Start

### 1. Look Up a Customer's Subscriptions

Find subscriptions by customer email or Shopify customer ID:


```bash
# By customer ID
curl -X GET "https://subscription-admin.appstle.com/api/external/v2/subscription-customers/{customerId}" \
  -H "X-API-Key: YOUR_API_KEY"
```

**Response includes:**

- Active, paused, and cancelled subscriptions
- Products and variants in each subscription
- Next billing date and frequency
- Shipping address and delivery method


### 2. Get Subscription Contract Details

Retrieve full details for a specific subscription:


```bash
curl -X GET "https://subscription-admin.appstle.com/api/external/v2/subscription-contract-details?contractId={contractId}" \
  -H "X-API-Key: YOUR_API_KEY"
```

### 3. Get Upcoming Orders

See what's scheduled next for a subscription:


```bash
curl -X GET "https://subscription-admin.appstle.com/api/external/v2/subscription-billing-attempts/top-orders?contractId={contractId}" \
  -H "X-API-Key: YOUR_API_KEY"
```

## Subscription Management

### Cancel a Subscription


```bash
curl -X DELETE "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts/{contractId}" \
  -H "X-API-Key: YOUR_API_KEY"
```

### Pause a Subscription


```bash
curl -X PUT "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-status" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contractId": "{contractId}", "status": "PAUSED"}'
```

### Resume a Subscription


```bash
curl -X PUT "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-status" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contractId": "{contractId}", "status": "ACTIVE"}'
```

### Reschedule Next Billing Date


```bash
curl -X PUT "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-billing-date" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contractId": "{contractId}", "nextBillingDate": "2026-03-15T00:00:00Z"}'
```

### Update Billing Frequency


```bash
curl -X PUT "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-billing-interval" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contractId": "{contractId}", "billingIntervalCount": 2, "billingInterval": "MONTH"}'
```

### Skip an Upcoming Order


```bash
curl -X PUT "https://subscription-admin.appstle.com/api/external/v2/subscription-billing-attempts/skip-order/{billingAttemptId}" \
  -H "X-API-Key: YOUR_API_KEY"
```

## Product Management

### Add a Product to a Subscription


```bash
curl -X PUT "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-add-line-item" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contractId": "{contractId}", "variantId": "{variantId}", "quantity": 1}'
```

### Remove a Product from a Subscription


```bash
curl -X PUT "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-remove-line-item" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contractId": "{contractId}", "lineId": "{lineId}"}'
```

### Update Product Quantity


```bash
curl -X PUT "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-line-item-quantity" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contractId": "{contractId}", "lineId": "{lineId}", "quantity": 3}'
```

## Discounts

### Apply a Discount Code


```bash
curl -X PUT "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-apply-discount" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contractId": "{contractId}", "discountCode": "SAVE10"}'
```

### Remove a Discount


```bash
curl -X PUT "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-remove-discount" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contractId": "{contractId}"}'
```

## Shipping

### Update Shipping Address


```bash
curl -X PUT "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-shipping-address" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contractId": "{contractId}",
    "address1": "123 Main St",
    "city": "San Francisco",
    "province": "California",
    "country": "United States",
    "zip": "94105"
  }'
```

## Past Orders

### Get Order History


```bash
curl -X GET "https://subscription-admin.appstle.com/api/external/v2/subscription-billing-attempts/past-orders?contractId={contractId}" \
  -H "X-API-Key: YOUR_API_KEY"
```

## Webhooks

Appstle supports webhooks for real-time event notifications. See the [Webhooks documentation](/webhooks) for setup and available events.

## Rate Limits

API requests are rate-limited per store. If you receive a `429 Too Many Requests` response, implement exponential backoff before retrying.

## Becoming a Partner

If you're building a product that integrates with subscription management (helpdesks, CRMs, AI agents, automation platforms), we'd love to work with you.

**What you get:**

- Dedicated partner key (bypasses merchant API paywall)
- Technical support during integration
- Co-marketing opportunities
- Listed in our integration directory


**Current partners:** ShipInsure, Zapiet, Zaymo, OrderLogix, and more.

**To apply:** Email [support@appstle.com](mailto:support@appstle.com) with:

- Your company name and product
- What Appstle data your integration needs access to
- Expected API call volume per merchant


We typically provision partner keys within 1-2 business days.

## Need Help?

- **Full API Reference:** See the [Admin APIs](/admin-api-swagger) and [Storefront APIs](/storefront-api-swagger) for complete endpoint documentation
- **Partners:** [support@appstle.com](mailto:support@appstle.com)
- **Support:** [support@appstle.com](mailto:support@appstle.com)