Skip to content
Last updated

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

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

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:

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

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

Pause a Subscription

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

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

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

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

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

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

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

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

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

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

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

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 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 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?

⚡ JavaScript Hooks

🤝 Partner Integration