# 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

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)

Endpoint: GET /api/external/v2/subscription-contract-details
Version: 0.0.1

## Header parameters:

  - `X-API-Key` (string, required)
    API Key for authentication
    Example: "sk_live_1234567890abcdef"

## Query parameters:

  - `fromCreatedDate` (string)
    Filter by subscriptions created on or after this date
    Example: "2025-10-01T00:00:00+02:00"

  - `toCreatedDate` (string)
    Filter by subscriptions created on or before this date
    Example: "2025-10-31T23:59:59+02:00"

  - `fromUpdatedDate` (string)
    Filter by subscriptions updated on or after this date
    Example: "2025-10-01T00:00:00+02:00"

  - `toUpdatedDate` (string)
    Filter by subscriptions updated on or before this date
    Example: "2025-10-31T23:59:59+02:00"

  - `fromNextDate` (string)
    Filter by subscriptions with next billing date on or after this date. Note: Both fromNextDate and toNextDate must be provided together
    Example: "2025-10-01T00:00:00+02:00"

  - `toNextDate` (string)
    Filter by subscriptions with next billing date on or before this date. Note: Both fromNextDate and toNextDate must be provided together
    Example: "2025-10-31T23:59:59+02:00"

  - `subscriptionContractId` (string)
    Filter by subscription contract ID (partial match supported, case-insensitive)
    Example: 123456

  - `customerName` (string)
    Filter by customer name or email (partial match, case-insensitive). Searches both customer_name and customer_email fields
    Example: "john"

  - `orderName` (string)
    Filter by order number (searches current order_name and historical orders in subscription_billing_attempt table, partial match)
    Example: "SUB-1001"

  - `status` (string)
    Filter by subscription status (case-insensitive)
    Enum: "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)
    Example: 1

  - `billingPolicyInterval` (string)
    Filter by delivery interval type (Note: This parameter name is misleading - it actually filters the delivery_policy_interval field)
    Enum: "DAY", "WEEK", "MONTH", "YEAR"

  - `planType` (string)
    Filter by plan type classification. 'prepaid' = billing interval count ≠ delivery interval count, 'non-prepaid' = billing interval count = delivery interval count
    Enum: "prepaid", "non-prepaid"

  - `recordType` (string)
    Filter by record type. 'imported' = has imported_id, 'nonImported' = no imported_id
    Enum: "imported", "nonImported"

  - `productId` (integer)
    Filter by product ID (searches within subscription line items JSON). Provide numeric ID only
    Example: 7890123456

  - `variantId` (integer)
    Filter by variant ID (searches within subscription line items JSON). Provide numeric ID only
    Example: 42549172011164

  - `sellingPlanId` (integer)
    Filter by selling plan ID (searches within subscription line items JSON). Provide numeric ID only
    Example: 123456

  - `minOrderAmount` (number)
    Filter by minimum total order amount (calculated from sum of line items: quantity * currentPrice)
    Example: 50

  - `maxOrderAmount` (number)
    Filter by maximum total order amount (calculated from sum of line items: quantity * currentPrice)
    Example: 500

  - `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.
    Example: "page=0&size=20&sort=next_billing_date,asc&sort=id,desc"

  - `api_key` (string)
    API Key (Deprecated - Use X-API-Key header instead)

## Response 200 fields (application/json):

  - `id` (integer)

  - `shop` (string, required)

  - `graphSubscriptionContractId` (string)

  - `subscriptionContractId` (integer)

  - `billingPolicyInterval` (string)

  - `billingPolicyIntervalCount` (integer)

  - `currencyCode` (string)

  - `customerId` (integer)

  - `graphCustomerId` (string)

  - `deliveryPolicyInterval` (string)

  - `deliveryPolicyIntervalCount` (integer)

  - `status` (string)

  - `graphOrderId` (string)

  - `orderId` (integer)

  - `createdAt` (string)

  - `updatedAt` (string)

  - `nextBillingDate` (string)

  - `orderAmount` (number)

  - `orderName` (string)

  - `customerName` (string)

  - `customerEmail` (string)

  - `subscriptionCreatedEmailSent` (boolean)

  - `endsAt` (string)

  - `startsAt` (string)

  - `subscriptionCreatedEmailSentStatus` (string)
    Enum: "SENT", "UNSENT", "FAILED", "EMAIL_SETTINGS_DISABLED", "CUSTOMER_PAYMENT_EMPTY", "CONTRACT_PAUSED_STATUS"

  - `minCycles` (integer)

  - `maxCycles` (integer)

  - `customerFirstName` (string)

  - `customerLastName` (string)

  - `autoCharge` (boolean)

  - `importedId` (string)

  - `stopUpComingOrderEmail` (boolean)

  - `pausedFromActive` (boolean)

  - `subscriptionCreatedSmsSentStatus` (string)
    Enum: "SENT", "UNSENT", "FAILED", "SMS_SETTINGS_DISABLED", "CUSTOMER_PAYMENT_EMPTY", "CONTRACT_PAUSED_STATUS", "PHONE_NUMBER_EMPTY"

  - `phone` (string)

  - `activatedOn` (string)

  - `pausedOn` (string)

  - `cancelledOn` (string)

  - `contractDetailsJSON` (string)

  - `deletedVariantIds` (string)

  - `cancellationFeedback` (string)

  - `orderNote` (string)

  - `orderNoteAttributes` (string)

  - `allowDeliveryPriceOverride` (boolean)

  - `disableFixEmptyQueue` (boolean)

  - `orderAmountUSD` (number)

  - `originType` (string)
    Enum: "STORE_FRONT", "IMPORTED", "SPLIT_ATTEMPT_BILLING", "SPLIT_CONTRACT"

  - `originalContractId` (integer)

  - `cancellationNote` (string)

  - `subscriptionType` (string)
    Enum: "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)

  - `upcomingEmailTaskUrl` (string)

  - `contractAmount` (number)

  - `contractAmountUSD` (number)

  - `lastSuccessfulOrder` (string)

  - `totalSuccessfulOrders` (integer)

  - `lifetimeValue` (number)

  - `lifetimeValueUSD` (number)

  - `allowDeliveryAddressOverride` (boolean)

  - `billingDateAfterTrial` (string)

  - `pauseReason` (string)

  - `pauseFeedback` (string)

  - `pauseTillDate` (string)

  - `pauseDurationCycle` (integer)

  - `emailBouncedOrFailed` (boolean)

  - `updatingQueue` (boolean)

  - `customerTag` (string)

  - `queueUpdatedAt` (string)

  - `orderAmountShopCurrency` (number)

  - `orderAmountContractCurrency` (number)

  - `billingCountryCode` (string)

  - `deliveryCountryCode` (string)


## Response 400 fields

## Response 401 fields

## Response 403 fields

## Response 500 fields