> ## Documentation Index > Fetch the complete documentation index at: https://developers.appstle.com/llms.txt > Use this file to discover all available pages before exploring further. # 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) ## OpenAPI ````yaml /subscription/admin-api-swagger.json get /api/external/v2/subscription-contract-details openapi: 3.0.1 info: description: >- Comprehensive API documentation for managing subscriptions, payments, and related operations. These APIs allow you to programmatically manage subscription lifecycles, handle payments, configure products, and integrate subscription functionality into your applications. title: Admin APIs version: 0.0.1 servers: - url: https://subscription-admin.appstle.com security: [] tags: - description: >- Core APIs for managing the complete subscription lifecycle including creation, updates, pausing, resuming, and cancellation of subscriptions. name: Subscription Management - description: >- APIs for managing subscription payment methods, processing payments, handling payment retries, and updating billing information. name: Subscription Payments - description: >- APIs for managing subscription contracts including delivery schedules, pricing, order notes, billing cycles, and shipping addresses. name: Subscription Contracts - description: >- APIs for managing products within subscriptions including adding, removing, updating quantities, and swapping products. name: Subscription Products - description: >- APIs for handling billing operations, payment processing, and financial transactions related to subscriptions. name: Billing & Payments - description: >- APIs for managing discounts and promotional codes applied to subscriptions. name: Subscription Discounts - description: >- APIs for managing one-time add-on products that can be purchased alongside recurring subscription items. name: Subscription One-Time Products - description: >- APIs for managing subscription plans, pricing tiers, and plan configurations. name: Subscription Plans - description: >- APIs for managing customizable product boxes and bundles where customers can select multiple items. name: Build-a-Box & Bundles - description: >- APIs for managing the product catalog including product information, variants, and inventory. name: Product Catalog - description: >- APIs for managing operational settings, configurations, and administrative functions. name: Operations & Settings - description: >- APIs powering the customer-facing portal where subscribers can manage their own subscriptions. name: Customer Portal - description: APIs for managing customer information, profiles, and account details. name: Customers - description: >- APIs for retrieving aggregated subscription data, customer subscription history, and account-level subscription information. name: Subscription Data - description: >- APIs for managing delivery profiles, shipping rates, free shipping configuration, and delivery method options on subscriptions. name: Delivery & Shipping - description: >- APIs for managing storefront customization including custom CSS, theme settings, label translations, and merchant-defined widget configuration. name: Customization - description: >- APIs for configuring cancellation flows, retention offers, cancellation reason management, and win-back automation. name: Customer Retention paths: /api/external/v2/subscription-contract-details: get: tags: - Subscription Contracts summary: Retrieve subscription contracts description: >- 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) operationId: getAllSubscriptionContractDetails parameters: - deprecated: true description: API Key (Deprecated - Use X-API-Key header instead) in: query name: api_key required: false schema: type: string - description: API Key for authentication example: sk_live_1234567890abcdef in: header name: X-API-Key required: true schema: type: string - description: Filter by subscriptions created on or after this date example: '2025-10-01T00:00:00+02:00' in: query name: fromCreatedDate required: false schema: format: date-time type: string - description: Filter by subscriptions created on or before this date example: '2025-10-31T23:59:59+02:00' in: query name: toCreatedDate required: false schema: format: date-time type: string - description: Filter by subscriptions updated on or after this date example: '2025-10-01T00:00:00+02:00' in: query name: fromUpdatedDate required: false schema: format: date-time type: string - description: Filter by subscriptions updated on or before this date example: '2025-10-31T23:59:59+02:00' in: query name: toUpdatedDate required: false schema: format: date-time type: string - description: >- 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' in: query name: fromNextDate required: false schema: format: date-time type: string - description: >- 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' in: query name: toNextDate required: false schema: format: date-time type: string - description: >- Filter by subscription contract ID (partial match supported, case-insensitive) example: 123456 in: query name: subscriptionContractId required: false schema: type: string - description: >- Filter by customer name or email (partial match, case-insensitive). Searches both customer_name and customer_email fields example: john in: query name: customerName required: false schema: type: string - description: >- Filter by order number (searches current order_name and historical orders in subscription_billing_attempt table, partial match) example: SUB-1001 in: query name: orderName required: false schema: type: string - description: Filter by subscription status (case-insensitive) example: ACTIVE in: query name: status required: false schema: enum: - ACTIVE - PAUSED - CANCELLED type: string - description: >- Filter by delivery interval count (Note: This parameter name is misleading - it actually filters the delivery_policy_interval_count field) example: 1 in: query name: billingPolicyIntervalCount required: false schema: maximum: 365 minimum: 1 type: integer - description: >- Filter by delivery interval type (Note: This parameter name is misleading - it actually filters the delivery_policy_interval field) example: MONTH in: query name: billingPolicyInterval required: false schema: enum: - DAY - WEEK - MONTH - YEAR type: string - description: >- Filter by plan type classification. 'prepaid' = billing interval count ≠ delivery interval count, 'non-prepaid' = billing interval count = delivery interval count example: prepaid in: query name: planType required: false schema: enum: - prepaid - non-prepaid type: string - description: >- Filter by record type. 'imported' = has imported_id, 'nonImported' = no imported_id example: imported in: query name: recordType required: false schema: enum: - imported - nonImported type: string - description: >- Filter by product ID (searches within subscription line items JSON). Provide numeric ID only example: 7890123456 in: query name: productId required: false schema: format: int64 type: integer - description: >- Filter by variant ID (searches within subscription line items JSON). Provide numeric ID only example: 42549172011164 in: query name: variantId required: false schema: format: int64 type: integer - description: >- Filter by selling plan ID (searches within subscription line items JSON). Provide numeric ID only example: 123456 in: query name: sellingPlanId required: false schema: format: int64 type: integer - description: >- Filter by minimum total order amount (calculated from sum of line items: quantity * currentPrice) example: 50 in: query name: minOrderAmount required: false schema: format: double type: number - description: >- Filter by maximum total order amount (calculated from sum of line items: quantity * currentPrice) example: 500 in: query name: maxOrderAmount required: false schema: format: double type: number - description: >- 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 in: query name: pageable required: true schema: $ref: '#/components/schemas/Pageable' responses: '200': content: application/json: examples: Success Response: description: Success Response value: - 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' 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' orderName: '#SUB-1002' status: paused subscriptionContractId: 123456790 totalPrice: 149.97 updatedAt: '2024-03-10T16:45:00.000+00:00' schema: items: $ref: '#/components/schemas/SubscriptionContractDetailsDTO' type: array description: Successfully retrieved subscription contracts headers: Link: description: Pagination navigation links (first, prev, next, last) schema: example: >- ; rel="next" type: string style: simple X-Total-Count: description: Total number of matching subscription contracts schema: example: 150 type: integer style: simple '400': content: application/json: examples: Invalid Date Format: description: Invalid Date Format value: detail: >- Date must be in format: yyyy-MM-dd'T'HH:mm:ssXXX (e.g., 2024-03-15T10:30:00+00:00 or 2024-03-15T10:30:00Z) status: 400 title: Invalid date format type: https://example.com/errors/bad-request Invalid Sort Field: description: Invalid Sort Field value: detail: >- Unknown column 'nextBillingDate'. Use snake_case column names for sorting (e.g., 'next_billing_date') status: 400 title: Invalid sort field type: https://example.com/errors/bad-request Invalid Status Value: description: Invalid Status Value value: detail: >- Status must be one of: ACTIVE, PAUSED, CANCELLED (case-insensitive) status: 400 title: Invalid status value type: https://example.com/errors/bad-request description: Bad Request - Invalid parameter format or values '401': content: application/json: example: detail: Valid API key is required to access this endpoint status: 401 title: Authentication required type: https://example.com/errors/unauthorized description: Authentication required - missing or invalid API key '403': content: application/json: example: detail: >- API key does not have permission to read subscription contracts status: 403 title: Insufficient permissions type: https://example.com/errors/forbidden description: Insufficient permissions to access subscription data '500': content: application/json: example: detail: >- An unexpected error occurred while retrieving subscription contracts status: 500 title: Internal server error type: https://example.com/errors/internal-error description: Internal server error components: schemas: Pageable: properties: page: format: int32 minimum: 0 type: integer size: format: int32 minimum: 1 type: integer sort: items: type: string type: array type: object SubscriptionContractDetailsDTO: properties: activatedOn: format: date-time type: string allowDeliveryAddressOverride: type: boolean allowDeliveryPriceOverride: type: boolean autoCharge: type: boolean billingCountryCode: type: string billingDateAfterTrial: format: date-time type: string billingPolicyInterval: type: string billingPolicyIntervalCount: format: int32 type: integer cancellationFeedback: type: string cancellationNote: type: string cancelledOn: format: date-time type: string contractAmount: format: double type: number contractAmountUSD: format: double type: number contractDetailsJSON: type: string createdAt: format: date-time type: string currencyCode: type: string customerEmail: type: string customerFirstName: type: string customerId: format: int64 type: integer customerLastName: type: string customerName: type: string customerTag: type: string deletedVariantIds: type: string deliveryCountryCode: type: string deliveryPolicyInterval: type: string deliveryPolicyIntervalCount: format: int32 type: integer disableFixEmptyQueue: type: boolean emailBouncedOrFailed: type: boolean endsAt: format: date-time type: string graphCustomerId: type: string graphOrderId: type: string graphSubscriptionContractId: type: string id: format: int64 type: integer importedId: type: string lastSuccessfulOrder: type: string lifetimeValue: format: double type: number lifetimeValueUSD: format: double type: number maxCycles: format: int32 type: integer minCycles: format: int32 type: integer nextBillingDate: format: date-time type: string nextPaidBillingDate: format: date-time type: string orderAmount: format: double type: number orderAmountContractCurrency: format: double type: number orderAmountShopCurrency: format: double type: number orderAmountUSD: format: double type: number orderId: format: int64 type: integer orderName: type: string orderNote: type: string orderNoteAttributes: type: string originType: enum: - STORE_FRONT - IMPORTED - SPLIT_ATTEMPT_BILLING - SPLIT_CONTRACT type: string originalContractId: format: int64 type: integer pauseDurationCycle: format: int32 type: integer pauseFeedback: type: string pauseReason: type: string pauseTillDate: format: date-time type: string pausedFromActive: type: boolean pausedOn: format: date-time type: string pendingCancellationCycle: format: int32 type: integer pendingCancellationDate: format: date-time type: string phone: type: string queueUpdatedAt: format: date-time type: string shop: type: string skipPaymentCreateUnpaidOrder: type: boolean startsAt: format: date-time type: string status: type: string stopUpComingOrderEmail: type: boolean subscriptionContractId: format: int64 type: integer subscriptionCreatedEmailSent: type: boolean subscriptionCreatedEmailSentStatus: enum: - SENT - UNSENT - FAILED - EMAIL_SETTINGS_DISABLED - CUSTOMER_PAYMENT_EMPTY - CONTRACT_PAUSED_STATUS type: string subscriptionCreatedSmsSentStatus: enum: - SENT - UNSENT - FAILED - SMS_SETTINGS_DISABLED - CUSTOMER_PAYMENT_EMPTY - CONTRACT_PAUSED_STATUS - PHONE_NUMBER_EMPTY type: string subscriptionType: enum: - REGULAR_SUBSCRIPTION - BUILD_A_BOX_CLASSIC - BUILD_A_BOX_SINGLE_PRODUCT - BUNDLING_CLASSIC - BUNDLING_MIX_AND_MATCH - SECTIONED_BUNDLE - VOLUME_DISCOUNT type: string subscriptionTypeIdentifier: type: string totalSuccessfulOrders: format: int32 type: integer upcomingEmailBufferDays: format: int32 type: integer upcomingEmailTaskUrl: type: string updatedAt: format: date-time type: string updatingQueue: type: boolean required: - shop type: object ````