Retrieve subscription contracts
Retrieves a paginated list of subscription contracts with powerful filtering capabilities. This endpoint enables complex queries to find specific subscriptions based on various criteria including dates, customer information, product details, and subscription characteristics.
Key Features:
- Comprehensive filtering across 20+ parameters
- Full pagination support with customizable page size
- Partial text matching for customer and order searches
- Date range filtering for multiple date fields
- Product and variant filtering within line items
- Order amount range filtering
- Plan type differentiation (prepaid vs pay-per-delivery)
Pagination:
- Send
page,sizeandsortas query parameters - Default page size: 20 items
- Maximum page size: 2000 items. A larger
sizeis treated as 2000 - Returns total count in X-Total-Count header
- Provides navigation links in Link header
List every contract:
- Send
sort=id,ascand asizeof up to2000, starting atpage=0 - Request the next page until the
Linkheader has norel="next"link, or until you have readX-Total-Countcontracts - Appstle gives each new contract a higher
id, so contracts created while you page land on the last page and don’t shift the pages you have read. A field that several contracts can share, such ascreated_at, can repeat or skip contracts at a page boundary - To pick up later changes, filter with
fromUpdatedDateset to the time your previous read started. A contract that changes while you page joins the list where itsidsorts and can repeat a contract at a page boundary, so store contracts byid
Sorting:
sort takes the field’s name in snake_case, not the camelCase name in the response. A camelCase name returns 400.
Common sorting examples:
sort=next_billing_date,asc(NOT nextBillingDate)sort=customer_name,desc(NOT customerName)sort=created_at,asc(NOT createdAt)sort=subscription_contract_id,desc(NOT subscriptionContractId)sort=order_amount,asc(NOT orderAmount)
Date Format:
All date parameters use ISO 8601 format with timezone:
yyyy-MM-dd'T'HH:mm:ssXXX
Examples: 2024-03-15T10:30:00+00:00 or 2024-03-15T10:30:00Z
Date Range Filtering:
- For created, updated dates: Can use either ‘from’, ‘to’, or both
- For next billing date: Both ‘from’ and ‘to’ must be provided together (current limitation)
Text Search Behavior:
- Customer name searches both name and email fields
- Order name searches the contract’s checkout order and its renewal orders
- All text searches are case-insensitive
- Partial matches are supported (contains logic)
- Subscription contract ID search supports partial numeric matching
Initial (checkout) order:
orderId,orderNameandcreatedAtdescribe the order placed at checkout that created the subscription, andorderAmountis this subscription’s share of that order- The external past orders endpoint lists the initial order only when filtered by contractId: it comes last, with id null, and is not counted in X-Total-Count. Use this endpoint with
fromCreatedDate/toCreatedDateto sync initial orders - Contracts with no Shopify origin order (e.g. imported or migrated from another app) have an empty
orderIdandorderNameset toUNKNOWN - For what a contract bills per renewal now, read
contractAmount, notorderAmount
nextPaidBillingDate:
- The next billing date on which the customer is actually charged.
- For prepaid/cycle-based plans with free or discounted reward cycles, this skips any upcoming cycle that is fully free and lands on the next cycle that gets charged - it can differ from
nextBillingDatein that case. - For plans without free cycles, or when no billing attempt has been scheduled yet, this equals
nextBillingDate. - Returns
nullwhen no future paid cycle exists (e.g., all remaining cycles are free and the plan’s max cycle count has been reached), or when contract pricing data is unavailable.
Plan Type Classification:
- prepaid: Billing interval > delivery interval
- non-prepaid: Billing interval = delivery interval
Performance Considerations:
- Complex filters (especially the product, variant, selling plan and order amount filters) can slow the response
- Use specific filters when possible
- Consider smaller page sizes for complex queries
- Product, variant and selling plan filters read every line of every contract, so they are the slowest on a large store
Authentication: Requires valid X-API-Key header (the deprecated ‘api_key’ query parameter is still accepted but not recommended)
curl --request GET \
--url https://subscription-admin.appstle.com/api/external/v2/subscription-contract-details \
--header 'X-API-Key: <x-api-key>'import requests
url = "https://subscription-admin.appstle.com/api/external/v2/subscription-contract-details"
headers = {"X-API-Key": "<x-api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-Key': '<x-api-key>'}};
fetch('https://subscription-admin.appstle.com/api/external/v2/subscription-contract-details', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const url = 'https://subscription-admin.appstle.com/api/external/v2/subscription-contract-details';
const options = {method: 'GET', headers: {'X-API-Key': '<x-api-key>'}};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://subscription-admin.appstle.com/api/external/v2/subscription-contract-details",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-API-Key: <x-api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://subscription-admin.appstle.com/api/external/v2/subscription-contract-details"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-Key", "<x-api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}require 'uri'
require 'net/http'
url = URI("https://subscription-admin.appstle.com/api/external/v2/subscription-contract-details")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<x-api-key>'
response = http.request(request)
puts response.read_body[
{
"activatedOn": "2026-10-26T02:52:06Z",
"billingPolicyInterval": "WEEK",
"billingPolicyIntervalCount": 1,
"cancelledOn": null,
"contractAmount": 44.96,
"contractAmountUSD": 44.96,
"contractDetailsJSON": "[{\"productId\":\"gid://shopify/Product/9876543210123\",\"sku\":\"\",\"title\":\"Alpine Glide Ski Wax\",\"quantity\":1,\"variantId\":\"gid://shopify/ProductVariant/50123456789012\",\"variantTitle\":\"Weekly Subscription\",\"variantImage\":\"https://cdn.shopify.com/s/files/1/0000/0000/0000/files/ski-wax.png\",\"currentPrice\":\"44.96\",\"sellingPlanId\":\"gid://shopify/SellingPlan/691234567890\",\"sellingPlanName\":\"Weekly Subscription\",\"lineId\":\"gid://shopify/SubscriptionLine/d47d84ee-c47e-402b-a57a-976c566a8384\",\"discountedPrice\":\"44.96\",\"pricingPolicyUpdated\":true,\"pricingPolicy\":{\"basePrice\":\"49.95\",\"cycleDiscounts\":[{\"afterCycle\":0,\"computedPrice\":\"44.96\",\"adjustmentType\":\"PERCENTAGE\",\"adjustmentValue\":\"10.0\"}]},\"basePrice\":\"49.95\",\"discountAllocations\":[]}]",
"createdAt": "2026-10-26T02:51:57Z",
"currencyCode": "USD",
"customerEmail": "jordan.rivera@example.com",
"customerFirstName": "Jordan",
"customerId": 31029995864368,
"customerLastName": "Rivera",
"customerName": "Jordan Rivera",
"customerTag": "appstle_subscription_active_customer",
"deliveryPolicyInterval": "WEEK",
"deliveryPolicyIntervalCount": 1,
"graphCustomerId": "gid://shopify/Customer/31029995864368",
"graphOrderId": "gid://shopify/Order/19138272493872",
"graphSubscriptionContractId": "gid://shopify/SubscriptionContract/193039565104",
"id": 13695469,
"lifetimeValue": 134.88,
"maxCycles": null,
"minCycles": null,
"nextBillingDate": "2026-11-16T03:00:00Z",
"nextPaidBillingDate": "2026-11-16T03:00:00Z",
"orderAmount": 44.96,
"orderId": 19138272493872,
"orderName": "#1067",
"pausedOn": null,
"shop": "your-store.myshopify.com",
"status": "active",
"subscriptionContractId": 193039565104,
"totalSuccessfulOrders": 3,
"updatedAt": "2026-11-09T18:17:47Z"
}
]Query Parameters
Response
Successfully retrieved subscription contracts
What the contract bills per renewal now, in currencyCode: the sum of its lines' discountedPrice in contractDetailsJSON (each line's price times quantity, after discounts). Shipping and tax are not included. On a prepaid contract, one renewal pays for every delivery until the next renewal. Appstle recalculates it when the contract is updated, so changes to lines, quantities and prices show up here. It is a floating-point number and can read like 84.60000000000001: round it to the currency's decimals before you show or compare it. For the checkout order, see orderAmount.
The contract's lines as a JSON string, not an array: parse it before you read it. Each line has productId, variantId, title, variantTitle, sku, quantity, lineId, sellingPlanId and sellingPlanName (empty strings when the line has no selling plan), discountAllocations (the IDs of the discounts on the line), and three prices sent as strings: currentPrice (one unit, per renewal, after the plan's discount; on a prepaid contract it covers every delivery the renewal pays for), discountedPrice (the line total: currentPrice times quantity, after manual and code discounts) and basePrice (one unit before the plan's discount, from pricingPolicy; on a line without pricingPolicy, currentPrice divided by the number of deliveries per renewal). A line can also have pricingPolicy (the plan's discount by cycle) and customAttributes.
This subscription's share of the order the customer placed at checkout: its lines' prices after discounts, times quantity, plus their tax when the store's prices don't include tax. Shipping and the order's other items are not included, so each subscription created by one order has its own orderAmount. It is in the store's currency, which can differ from currencyCode, and it is null when the contract has no checkout order (orderName is UNKNOWN). For what the contract bills per renewal now, use contractAmount.
curl --request GET \
--url https://subscription-admin.appstle.com/api/external/v2/subscription-contract-details \
--header 'X-API-Key: <x-api-key>'import requests
url = "https://subscription-admin.appstle.com/api/external/v2/subscription-contract-details"
headers = {"X-API-Key": "<x-api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-Key': '<x-api-key>'}};
fetch('https://subscription-admin.appstle.com/api/external/v2/subscription-contract-details', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const url = 'https://subscription-admin.appstle.com/api/external/v2/subscription-contract-details';
const options = {method: 'GET', headers: {'X-API-Key': '<x-api-key>'}};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://subscription-admin.appstle.com/api/external/v2/subscription-contract-details",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-API-Key: <x-api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://subscription-admin.appstle.com/api/external/v2/subscription-contract-details"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-Key", "<x-api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}require 'uri'
require 'net/http'
url = URI("https://subscription-admin.appstle.com/api/external/v2/subscription-contract-details")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<x-api-key>'
response = http.request(request)
puts response.read_body[
{
"activatedOn": "2026-10-26T02:52:06Z",
"billingPolicyInterval": "WEEK",
"billingPolicyIntervalCount": 1,
"cancelledOn": null,
"contractAmount": 44.96,
"contractAmountUSD": 44.96,
"contractDetailsJSON": "[{\"productId\":\"gid://shopify/Product/9876543210123\",\"sku\":\"\",\"title\":\"Alpine Glide Ski Wax\",\"quantity\":1,\"variantId\":\"gid://shopify/ProductVariant/50123456789012\",\"variantTitle\":\"Weekly Subscription\",\"variantImage\":\"https://cdn.shopify.com/s/files/1/0000/0000/0000/files/ski-wax.png\",\"currentPrice\":\"44.96\",\"sellingPlanId\":\"gid://shopify/SellingPlan/691234567890\",\"sellingPlanName\":\"Weekly Subscription\",\"lineId\":\"gid://shopify/SubscriptionLine/d47d84ee-c47e-402b-a57a-976c566a8384\",\"discountedPrice\":\"44.96\",\"pricingPolicyUpdated\":true,\"pricingPolicy\":{\"basePrice\":\"49.95\",\"cycleDiscounts\":[{\"afterCycle\":0,\"computedPrice\":\"44.96\",\"adjustmentType\":\"PERCENTAGE\",\"adjustmentValue\":\"10.0\"}]},\"basePrice\":\"49.95\",\"discountAllocations\":[]}]",
"createdAt": "2026-10-26T02:51:57Z",
"currencyCode": "USD",
"customerEmail": "jordan.rivera@example.com",
"customerFirstName": "Jordan",
"customerId": 31029995864368,
"customerLastName": "Rivera",
"customerName": "Jordan Rivera",
"customerTag": "appstle_subscription_active_customer",
"deliveryPolicyInterval": "WEEK",
"deliveryPolicyIntervalCount": 1,
"graphCustomerId": "gid://shopify/Customer/31029995864368",
"graphOrderId": "gid://shopify/Order/19138272493872",
"graphSubscriptionContractId": "gid://shopify/SubscriptionContract/193039565104",
"id": 13695469,
"lifetimeValue": 134.88,
"maxCycles": null,
"minCycles": null,
"nextBillingDate": "2026-11-16T03:00:00Z",
"nextPaidBillingDate": "2026-11-16T03:00:00Z",
"orderAmount": 44.96,
"orderId": 19138272493872,
"orderName": "#1067",
"pausedOn": null,
"shop": "your-store.myshopify.com",
"status": "active",
"subscriptionContractId": 193039565104,
"totalSuccessfulOrders": 3,
"updatedAt": "2026-11-09T18:17:47Z"
}
]