Subscription Contracts

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:

Uses Spring’s Pageable format
Default page size: 20 items
Maximum page size: 2000 items (exceeding this limit will result in a 400 error)
Returns total count in X-Total-Count header
Provides navigation links in Link header

IMPORTANT - Sorting Limitations: Due to the use of native SQL queries, sort parameters MUST use database column names (snake_case) rather than Java field names (camelCase).

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 current and historical orders (in subscription_billing_attempt table)
All text searches are case-insensitive
Partial matches are supported (contains logic)
Subscription contract ID search supports partial numeric matching

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 nextBillingDate in that case.
For plans without free cycles, or when no billing attempt has been scheduled yet, this equals nextBillingDate.
Returns null only when no future paid cycle exists (e.g., all remaining cycles are free and the plan’s max cycle count has been reached).

Plan Type Classification:

prepaid: Billing interval > delivery interval
non-prepaid: Billing interval = delivery interval

Performance Considerations:

Complex filters (especially JSON searches and order amount calculations) may impact response time
Use specific filters when possible
Consider smaller page sizes for complex queries
Product, variant, and selling plan searches use JSON_SEARCH which may be slow on large datasets

Authentication: Requires valid X-API-Key header (the deprecated ‘api_key’ query parameter is still accepted but not recommended)

GET

api

external

subscription-contract-details

Retrieve subscription contracts

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": "2024-01-15T08:00:00.000+00:00",
    "billingPolicyInterval": "MONTH",
    "billingPolicyIntervalCount": 1,
    "cancelledOn": null,
    "contractDetailsJson": [
      {
        "currentPrice": 99.99,
        "productId": "gid://shopify/Product/7890123456",
        "productTitle": "Premium Subscription Box",
        "quantity": 1,
        "sellingPlanId": "gid://shopify/SellingPlan/123456",
        "sellingPlanName": "Deliver every month",
        "variantId": "gid://shopify/ProductVariant/42549172011164",
        "variantTitle": "Monthly Plan"
      }
    ],
    "createdAt": "2024-01-15T08:00:00.000+00:00",
    "currencyCode": "USD",
    "customerEmail": "john.doe@example.com",
    "customerId": 987654321,
    "customerName": "John Doe",
    "deliveryPolicyInterval": "MONTH",
    "deliveryPolicyIntervalCount": 1,
    "graphSubscriptionContractId": "gid://shopify/SubscriptionContract/123456789",
    "id": 1001,
    "importedId": null,
    "maxCycles": null,
    "minCycles": 3,
    "nextBillingDate": "2024-04-01T12:00:00.000+00:00",
    "nextPaidBillingDate": "2024-04-01T12:00:00.000+00:00",
    "orderName": "#SUB-1001",
    "pausedOn": null,
    "status": "active",
    "subscriptionContractId": 123456789,
    "totalPrice": 99.99,
    "updatedAt": "2024-03-01T14:30:00.000+00:00"
  },
  {
    "billingPolicyInterval": "MONTH",
    "billingPolicyIntervalCount": 3,
    "createdAt": "2024-02-01T10:00:00.000+00:00",
    "currencyCode": "USD",
    "customerEmail": "jane.smith@example.com",
    "customerId": 987654322,
    "customerName": "Jane Smith",
    "deliveryPolicyInterval": "MONTH",
    "deliveryPolicyIntervalCount": 1,
    "id": 1002,
    "nextBillingDate": "2024-05-01T12:00:00.000+00:00",
    "nextPaidBillingDate": "2024-07-01T12:00:00.000+00:00",
    "orderName": "#SUB-1002",
    "status": "paused",
    "subscriptionContractId": 123456790,
    "totalPrice": 149.97,
    "updatedAt": "2024-03-10T16:45:00.000+00:00"
  }
]

Headers

X-API-Key

string

required

API Key for authentication

Query Parameters

api_key

string

API Key (Deprecated - Use X-API-Key header instead)

fromCreatedDate

string<date-time>

Filter by subscriptions created on or after this date

toCreatedDate

string<date-time>

Filter by subscriptions created on or before this date

fromUpdatedDate

string<date-time>

Filter by subscriptions updated on or after this date

toUpdatedDate

string<date-time>

Filter by subscriptions updated on or before this date

fromNextDate

string<date-time>

Filter by subscriptions with next billing date on or after this date. Note: Both fromNextDate and toNextDate must be provided together

toNextDate

string<date-time>

Filter by subscriptions with next billing date on or before this date. Note: Both fromNextDate and toNextDate must be provided together

subscriptionContractId

string

Filter by subscription contract ID (partial match supported, case-insensitive)

customerName

string

Filter by customer name or email (partial match, case-insensitive). Searches both customer_name and customer_email fields

orderName

string

Filter by order number (searches current order_name and historical orders in subscription_billing_attempt table, partial match)

status

enum<string>

Filter by subscription status (case-insensitive)

Available options:

ACTIVE,

PAUSED,

CANCELLED

billingPolicyIntervalCount

integer

Filter by delivery interval count (Note: This parameter name is misleading - it actually filters the delivery_policy_interval_count field)

Required range: 1 <= x <= 365

billingPolicyInterval

enum<string>

Filter by delivery interval type (Note: This parameter name is misleading - it actually filters the delivery_policy_interval field)

Available options:

DAY,

WEEK,

MONTH,

YEAR

planType

enum<string>

Filter by plan type classification. 'prepaid' = billing interval count ≠ delivery interval count, 'non-prepaid' = billing interval count = delivery interval count

Available options:

prepaid,

non-prepaid

recordType

enum<string>

Filter by record type. 'imported' = has imported_id, 'nonImported' = no imported_id

Available options:

imported,

nonImported

productId

integer<int64>

Filter by product ID (searches within subscription line items JSON). Provide numeric ID only

variantId

integer<int64>

Filter by variant ID (searches within subscription line items JSON). Provide numeric ID only

sellingPlanId

integer<int64>

Filter by selling plan ID (searches within subscription line items JSON). Provide numeric ID only

minOrderAmount

number<double>

Filter by minimum total order amount (calculated from sum of line items: quantity * currentPrice)

maxOrderAmount

number<double>

Filter by maximum total order amount (calculated from sum of line items: quantity * currentPrice)

pageable

object

required

Pagination and sorting parameters. IMPORTANT: Sort fields must use database column names (snake_case), not Java field names. Maximum page size is 2000.

Show child attributes

Response

Successfully retrieved subscription contracts

shop

string

required

activatedOn

string<date-time>

allowDeliveryAddressOverride

boolean

allowDeliveryPriceOverride

boolean

autoCharge

boolean

billingCountryCode

string

billingDateAfterTrial

string<date-time>

billingPolicyInterval

string

billingPolicyIntervalCount

integer<int32>

cancellationFeedback

string

cancellationNote

string

cancelledOn

string<date-time>

contractAmount

number<double>

contractAmountUSD

number<double>

contractDetailsJSON

string

createdAt

string<date-time>

currencyCode

string

customerEmail

string

customerFirstName

string

customerId

integer<int64>

customerLastName

string

customerName

string

customerTag

string

deletedVariantIds

string

deliveryCountryCode

string

deliveryPolicyInterval

string

deliveryPolicyIntervalCount

integer<int32>

disableFixEmptyQueue

boolean

emailBouncedOrFailed

boolean

endsAt

string<date-time>

graphCustomerId

string

graphOrderId

string

graphSubscriptionContractId

string

integer<int64>

importedId

string

lastSuccessfulOrder

string

lifetimeValue

number<double>

lifetimeValueUSD

number<double>

maxCycles

integer<int32>

minCycles

integer<int32>

nextBillingDate

string<date-time>

nextPaidBillingDate

string<date-time>

orderAmount

number<double>

orderAmountContractCurrency

number<double>

orderAmountShopCurrency

number<double>

orderAmountUSD

number<double>

orderId

integer<int64>

orderName

string

orderNote

string

orderNoteAttributes

string

originType

enum<string>

Available options:

STORE_FRONT,

IMPORTED,

SPLIT_ATTEMPT_BILLING,

SPLIT_CONTRACT

originalContractId

integer<int64>

pauseDurationCycle

integer<int32>

pauseFeedback

string

pauseReason

string

pauseTillDate

string<date-time>

pausedFromActive

boolean

pausedOn

string<date-time>

pendingCancellationCycle

integer<int32>

pendingCancellationDate

string<date-time>

phone

string

queueUpdatedAt

string<date-time>

skipPaymentCreateUnpaidOrder

boolean

startsAt

string<date-time>

status

string

stopUpComingOrderEmail

boolean

subscriptionContractId

integer<int64>

subscriptionCreatedEmailSent

boolean

subscriptionCreatedEmailSentStatus

enum<string>

Available options:

SENT,

UNSENT,

FAILED,

EMAIL_SETTINGS_DISABLED,

CUSTOMER_PAYMENT_EMPTY,

CONTRACT_PAUSED_STATUS

subscriptionCreatedSmsSentStatus

enum<string>

Available options:

SENT,

UNSENT,

FAILED,

SMS_SETTINGS_DISABLED,

CUSTOMER_PAYMENT_EMPTY,

CONTRACT_PAUSED_STATUS,

PHONE_NUMBER_EMPTY

subscriptionType

enum<string>

Available options:

REGULAR_SUBSCRIPTION,

BUILD_A_BOX_CLASSIC,

BUILD_A_BOX_SINGLE_PRODUCT,

BUNDLING_CLASSIC,

BUNDLING_MIX_AND_MATCH,

SECTIONED_BUNDLE,

VOLUME_DISCOUNT

subscriptionTypeIdentifier

string

totalSuccessfulOrders

integer<int32>

upcomingEmailBufferDays

integer<int32>

upcomingEmailTaskUrl

string

updatedAt

string<date-time>

updatingQueue

boolean

Retrieve subscription contracts

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": "2024-01-15T08:00:00.000+00:00",
    "billingPolicyInterval": "MONTH",
    "billingPolicyIntervalCount": 1,
    "cancelledOn": null,
    "contractDetailsJson": [
      {
        "currentPrice": 99.99,
        "productId": "gid://shopify/Product/7890123456",
        "productTitle": "Premium Subscription Box",
        "quantity": 1,
        "sellingPlanId": "gid://shopify/SellingPlan/123456",
        "sellingPlanName": "Deliver every month",
        "variantId": "gid://shopify/ProductVariant/42549172011164",
        "variantTitle": "Monthly Plan"
      }
    ],
    "createdAt": "2024-01-15T08:00:00.000+00:00",
    "currencyCode": "USD",
    "customerEmail": "john.doe@example.com",
    "customerId": 987654321,
    "customerName": "John Doe",
    "deliveryPolicyInterval": "MONTH",
    "deliveryPolicyIntervalCount": 1,
    "graphSubscriptionContractId": "gid://shopify/SubscriptionContract/123456789",
    "id": 1001,
    "importedId": null,
    "maxCycles": null,
    "minCycles": 3,
    "nextBillingDate": "2024-04-01T12:00:00.000+00:00",
    "nextPaidBillingDate": "2024-04-01T12:00:00.000+00:00",
    "orderName": "#SUB-1001",
    "pausedOn": null,
    "status": "active",
    "subscriptionContractId": 123456789,
    "totalPrice": 99.99,
    "updatedAt": "2024-03-01T14:30:00.000+00:00"
  },
  {
    "billingPolicyInterval": "MONTH",
    "billingPolicyIntervalCount": 3,
    "createdAt": "2024-02-01T10:00:00.000+00:00",
    "currencyCode": "USD",
    "customerEmail": "jane.smith@example.com",
    "customerId": 987654322,
    "customerName": "Jane Smith",
    "deliveryPolicyInterval": "MONTH",
    "deliveryPolicyIntervalCount": 1,
    "id": 1002,
    "nextBillingDate": "2024-05-01T12:00:00.000+00:00",
    "nextPaidBillingDate": "2024-07-01T12:00:00.000+00:00",
    "orderName": "#SUB-1002",
    "status": "paused",
    "subscriptionContractId": 123456790,
    "totalPrice": 149.97,
    "updatedAt": "2024-03-10T16:45:00.000+00:00"
  }
]

Get Started

Guides

Partner Integration

Webhooks

Admin API

Storefront API

Resources

Retrieve subscription contracts

Headers

Query Parameters

Response