# Get membership/subscription contract list

Retrieves a paginated list of membership/subscription contracts with advanced filtering capabilities. This endpoint provides comprehensive access to all subscription contracts in your store with flexible query options.

Key Information Returned:
- Contract Details: Contract ID, status, creation date, billing cycle
- Customer Information: Customer name, email, Shopify customer ID
- Subscription Items: Products, variants, quantities in subscription
- Billing Information: Next billing date, billing frequency, pricing
- Delivery Details: Shipping address, delivery method, next delivery date
- Plan Information: Membership plan type, selling plan IDs
- Status Tracking: Active, paused, cancelled, expired states

Filtering Capabilities:
- Date Ranges: Filter by creation date or next billing date
- Customer Search: Search by customer name or email
- Status Filter: Filter by contract status (active, paused, cancelled)
- Plan Type: Filter by membership plan type
- Billing Frequency: Filter by billing interval (weekly, monthly, etc.)
- Product/Variant: Find contracts containing specific products or variants
- Order Name: Search by Shopify order name/number
- Selling Plan: Filter by Shopify selling plan IDs
- Special Filters: Contracts with deleted products or bounced emails

Pagination:
- Supports standard pagination parameters (page, size, sort)
- Returns pagination headers for total count and navigation
- Default page size configurable via request parameters

Use Cases:
- Export subscription data to external CRM or analytics systems
- Build custom subscription dashboards and reports
- Sync membership data with external platforms
- Identify subscriptions needing attention (bounced emails, deleted products)
- Generate subscription activity reports by date range
- Find all subscriptions for a specific product or variant
- Monitor subscription health and churn metrics

Authentication: Requires API key authentication via X-API-Key header or api_key parameter

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

## Query parameters:

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

  - `fromCreatedDate` (string)
    Filter contracts created on or after this date
    Example: "2024-01-01T00:00:00Z"

  - `toCreatedDate` (string)
    Filter contracts created on or before this date
    Example: "2024-12-31T23:59:59Z"

  - `fromNextDate` (string)
    Filter contracts with next billing date on or after this date
    Example: "2024-01-01T00:00:00Z"

  - `toNextDate` (string)
    Filter contracts with next billing date on or before this date
    Example: "2024-12-31T23:59:59Z"

  - `subscriptionContractId` (string)
    Filter by specific subscription/membership contract ID
    Example: "gid://shopify/SubscriptionContract/12345"

  - `customerName` (string)
    Filter by customer name or email (partial match)
    Example: "john@example.com"

  - `orderName` (string)
    Filter by Shopify order name
    Example: "#1001"

  - `status` (string)
    Filter by subscription status
    Enum: "ACTIVE", "PAUSED", "CANCELLED", "FAILED", "EXPIRED"

  - `billingPolicyIntervalCount` (integer)
    Filter by billing frequency count (e.g., 1 for every 1 month)
    Example: 1

  - `billingPolicyInterval` (string)
    Filter by billing frequency interval
    Enum: "DAY", "WEEK", "MONTH", "YEAR"

  - `planType` (string)
    Filter by plan type (PAY_AS_YOU_GO or PREPAID)
    Enum: "PAY_AS_YOU_GO", "PREPAID"

  - `recordType` (string)
    Filter by record type (CONTRACT or SELLING_PLAN_GROUP)
    Example: "CONTRACT"

  - `productId` (integer)
    Filter by Shopify product ID
    Example: 123456789

  - `variantId` (integer)
    Filter by Shopify product variant ID
    Example: 987654321

  - `sellingPlanIds` (string)
    Filter by selling plan IDs (comma-separated for multiple)
    Example: "123,456,789"

  - `havingProductsDeletedFromStore` (boolean)
    Include only contracts with products deleted from Shopify store

  - `emailBouncedOrFailed` (boolean)
    Include only contracts where email notifications bounced or failed

  - `pageable` (object, required)
    Pagination parameters (page number and size)
    Example: {"page":0,"size":10,"sort":["id,desc"]}

## Header parameters:

  - `X-API-Key` (string)

## 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)

  - `cancellationFeedback` (string)

  - `orderNote` (string)

  - `orderNoteAttributes` (string)

  - `allowDeliveryPriceOverride` (boolean)

  - `orderAmountUSD` (number)

  - `billingDateAfterTrial` (string)

  - `trialEndDate` (string)

  - `pausedBySecurityChallenge` (boolean)

  - `dunning` (boolean)

  - `contractAmount` (number)

  - `contractAmountUSD` (number)

  - `upcomingSwapRule` (string)

  - `emailBouncedOrFailed` (boolean)

## Response 400 fields (*/*):

  - `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)

  - `cancellationFeedback` (string)

  - `orderNote` (string)

  - `orderNoteAttributes` (string)

  - `allowDeliveryPriceOverride` (boolean)

  - `orderAmountUSD` (number)

  - `billingDateAfterTrial` (string)

  - `trialEndDate` (string)

  - `pausedBySecurityChallenge` (boolean)

  - `dunning` (boolean)

  - `contractAmount` (number)

  - `contractAmountUSD` (number)

  - `upcomingSwapRule` (string)

  - `emailBouncedOrFailed` (boolean)

## Response 401 fields (*/*):

  - `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)

  - `cancellationFeedback` (string)

  - `orderNote` (string)

  - `orderNoteAttributes` (string)

  - `allowDeliveryPriceOverride` (boolean)

  - `orderAmountUSD` (number)

  - `billingDateAfterTrial` (string)

  - `trialEndDate` (string)

  - `pausedBySecurityChallenge` (boolean)

  - `dunning` (boolean)

  - `contractAmount` (number)

  - `contractAmountUSD` (number)

  - `upcomingSwapRule` (string)

  - `emailBouncedOrFailed` (boolean)