Appstle Subscriptions integration guide

This guide covers everything you need to build a full integration with Appstle Subscriptions. It assumes you already have an API key — if not, see the Authentication page first.

Base URL

All Admin API endpoints share this base URL:

https://subscription-admin.appstle.com/api/external/v2/

Authentication

Pass your API key in the X-API-Key header on every request:

curl -H "X-API-Key: apst_your-api-key-here" \
  "https://subscription-admin.appstle.com/api/external/v2/..."

For partner integrations that connect on behalf of multiple merchants, use the Partner Integration Framework. After a merchant approves a Nonce Handshake connection, Appstle issues your application a scoped API token for that merchant. Send that token as X-API-Key:

curl -H "X-API-Key: apst_scoped-partner-token" \
  "https://subscription-admin.appstle.com/api/external/v2/..."

See Authentication for merchant API key management and Partner integration for the complete connection flow.

Looking up customer subscriptions

Get all subscriptions for a customer

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

The response includes active, paused, and cancelled subscriptions along with products, next billing date, shipping address, and delivery method.

Check if a customer has active subscriptions

Returns an array of subscription contract IDs. An empty array means no active subscriptions.

curl -X GET \
  "https://subscription-admin.appstle.com/api/external/v2/subscription-customers/valid/{customerId}" \
  -H "X-API-Key: YOUR_API_KEY"

Get full contract details

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

Get upcoming orders

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"}'

Valid status values are ACTIVE, PAUSED, and CANCELLED.

Reschedule the 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"}'

Valid billingInterval values: DAY, WEEK, MONTH, YEAR.

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"

Rate limits

Requests are rate-limited per store. If you receive a 429 Too Many Requests response, implement exponential backoff before retrying. Do not immediately retry at full speed.

Partner integrations

If you are building a platform that connects to Appstle on behalf of multiple merchants, use the Partner Integration Framework. It provides:

A standard connection and merchant-approval flow
One isolated, revocable API token per connected merchant
External API access without requiring each merchant to purchase API access
Automatic token revocation when a merchant disconnects

Your Partner Secret authenticates /api/partner/... connection calls through X-Partner-Secret. After an approved Nonce Handshake, use the issued merchant-scoped token as X-API-Key when calling /api/external/v2/.... To get onboarded, email support@appstle.com with your company name, product description, base URL, and contact email. The Partner integration guide lists the complete onboarding requirements and implementation steps.

Webhooks

Receive real-time events when subscriptions change.

Shopify Flow

No-code automation using Shopify’s built-in workflow engine.

Authentication

Create, rotate, and revoke merchant API keys.

Partner integration

Connect your platform and receive scoped API tokens for merchants.

Get Started

Guides

Partner Integration

Webhooks

Admin API

Storefront API

Resources

Appstle Subscriptions integration guide

Base URL

Authentication

Looking up customer subscriptions

Get all subscriptions for a customer

Check if a customer has active subscriptions

Get full contract details

Get upcoming orders

Subscription management

Cancel a subscription

Pause a subscription

Resume a subscription

Reschedule the next billing date

Update billing frequency

Skip an upcoming order

Product management

Add a product to a subscription

Remove a product from a subscription

Update product quantity

Discounts

Apply a discount code

Remove a discount

Shipping

Update shipping address

Past orders

Get order history

Rate limits

Partner integrations

Further reading

Webhooks

Shopify Flow

Authentication

Partner integration

​Base URL

​Authentication

​Looking up customer subscriptions

​Get all subscriptions for a customer

​Check if a customer has active subscriptions

​Get full contract details

​Get upcoming orders

​Subscription management

​Cancel a subscription

​Pause a subscription

​Resume a subscription

​Reschedule the next billing date

​Update billing frequency

​Skip an upcoming order

​Product management

​Add a product to a subscription

​Remove a product from a subscription

​Update product quantity

​Discounts

​Apply a discount code

​Remove a discount

​Shipping

​Update shipping address

​Past orders

​Get order history

​Rate limits

​Partner integrations

​Further reading

Webhooks

Shopify Flow

Authentication

Partner integration

Base URL

Authentication

Looking up customer subscriptions

Get all subscriptions for a customer

Check if a customer has active subscriptions

Get full contract details

Get upcoming orders

Subscription management

Cancel a subscription

Pause a subscription

Resume a subscription

Reschedule the next billing date

Update billing frequency

Skip an upcoming order

Product management

Add a product to a subscription

Remove a product from a subscription

Update product quantity

Discounts

Apply a discount code

Remove a discount

Shipping

Update shipping address

Past orders

Get order history

Rate limits

Partner integrations

Further reading