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.

Full behavior, validation rules, and side effects

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

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/v2/subscription-contract-details

Retrieve subscription contracts

cURL

curl --request GET \
  --url https://subscription-admin.appstle.com/api/external/v2/subscription-contract-details \
  --header 'X-API-Key: <x-api-key>'

200

Success Response

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

200

application/json

Successfully retrieved subscription contracts

shop · string · required

id · integer<int64>

graphSubscriptionContractId · string

subscriptionContractId · integer<int64>

billingPolicyInterval · string

billingPolicyIntervalCount · integer<int32>

currencyCode · string

customerId · integer<int64>

graphCustomerId · string

deliveryPolicyInterval · string

deliveryPolicyIntervalCount · integer<int32>

status · string

graphOrderId · string

orderId · integer<int64>

createdAt · string<date-time>

updatedAt · string<date-time>

nextBillingDate · string<date-time>

orderAmount · number<double>

orderName · string

customerName · string

customerEmail · string

subscriptionCreatedEmailSent · boolean

endsAt · string<date-time>

startsAt · string<date-time>

subscriptionCreatedEmailSentStatus · enum<string>

Available options: SENT, UNSENT, FAILED, EMAIL_SETTINGS_DISABLED, CUSTOMER_PAYMENT_EMPTY, CONTRACT_PAUSED_STATUS

minCycles · integer<int32>

maxCycles · integer<int32>

customerFirstName · string

customerLastName · string

autoCharge · boolean

importedId · string

stopUpComingOrderEmail · boolean

pausedFromActive · boolean

skipPaymentCreateUnpaidOrder · boolean

subscriptionCreatedSmsSentStatus · enum<string>

Available options: SENT, UNSENT, FAILED, SMS_SETTINGS_DISABLED, CUSTOMER_PAYMENT_EMPTY, CONTRACT_PAUSED_STATUS, PHONE_NUMBER_EMPTY

phone · string

activatedOn · string<date-time>

pausedOn · string<date-time>

cancelledOn · string<date-time>

contractDetailsJSON · string

deletedVariantIds · string

cancellationFeedback · string

orderNote · string

orderNoteAttributes · string

allowDeliveryPriceOverride · boolean

disableFixEmptyQueue · boolean

orderAmountUSD · number<double>

originType · enum<string>

Available options: STORE_FRONT, IMPORTED, SPLIT_ATTEMPT_BILLING, SPLIT_CONTRACT

originalContractId · integer<int64>

cancellationNote · string

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

upcomingEmailBufferDays · integer<int32>

upcomingEmailTaskUrl · string

contractAmount · number<double>

contractAmountUSD · number<double>

lastSuccessfulOrder · string

totalSuccessfulOrders · integer<int32>

lifetimeValue · number<double>

lifetimeValueUSD · number<double>

allowDeliveryAddressOverride · boolean

billingDateAfterTrial · string<date-time>

pauseReason · string

pauseFeedback · string

pauseTillDate · string<date-time>

pauseDurationCycle · integer<int32>

pendingCancellationCycle · integer<int32>

pendingCancellationDate · string<date-time>

emailBouncedOrFailed · boolean

updatingQueue · boolean

customerTag · string

queueUpdatedAt · string<date-time>

orderAmountShopCurrency · number<double>

orderAmountContractCurrency · number<double>

billingCountryCode · string

deliveryCountryCode · string

nextPaidBillingDate · string<date-time>