> ## 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. # Get detailed subscription information for a customer > Retrieves comprehensive subscription contract details for a specific customer, including subscription status, products, billing information, delivery schedules, and more. This endpoint returns full subscription objects with all associated data, making it ideal for displaying subscription management interfaces and detailed analytics. **What This Endpoint Returns:** Unlike the contract IDs endpoint which returns only numeric IDs, this endpoint provides complete SubscriptionContractDetailsDTO objects for each of the customer's subscriptions. Each object contains all information needed to display and manage a subscription. **Data Included in Response:** **Subscription Identity:** - Subscription contract ID (Shopify numeric ID) - Subscription GraphQL ID (Shopify GID format) - Internal Appstle database ID - Contract creation date **Subscription Status & Lifecycle:** - Current status (ACTIVE, PAUSED, CANCELLED, EXPIRED, FAILED) - Status reason (why paused/cancelled) - Next billing date and time - Contract anchor date - Cancellation date (if applicable) - Current billing cycle number - Min/max cycle limits **Billing Configuration:** - Billing interval (WEEK, MONTH, YEAR) - Billing interval count (e.g., every 2 weeks) - Billing policy (pricing details) - Currency code - Recurring total price - Applied discounts and pricing policies **Delivery Configuration:** - Delivery interval (WEEK, MONTH, YEAR) - Delivery interval count - Delivery method (SHIPPING, PICK_UP, LOCAL_DELIVERY) - Delivery policy details - Delivery price **Products & Line Items:** - All subscribed products and variants - Product titles, SKUs, and images - Quantities per product - Individual line item prices - Product-specific discounts - Line item attributes and custom fields **Customer Information:** - Customer ID and GraphQL ID - Customer name and email - Customer acceptance status **Address Details:** - Billing address (full address object) - Shipping address (full address object) - Address validation status **Payment Information:** - Payment instrument type - Payment method details (card last 4, etc.) - Payment gateway used **Order & Fulfillment:** - Last order ID and details - Last order date - Order note - Fulfillment status **Additional Metadata:** - Custom note attributes - Tags and labels - Internal flags and settings - Selling plan ID and group ID - Shop domain **Use Cases:** **1. Customer Portal:** - Display all subscriptions on customer dashboard - Show subscription details page - Enable subscription management actions - Display upcoming order information **2. Admin Dashboard:** - View customer's complete subscription portfolio - Analyze subscription health and status - Identify at-risk or high-value subscriptions - Generate customer subscription reports **3. Customer Support:** - Quick access to all customer subscription details - Troubleshoot billing or delivery issues - Verify subscription configurations - Assist with subscription modifications **4. Analytics & Reporting:** - Calculate customer lifetime value - Analyze subscription mix per customer - Track subscription frequency distribution - Identify cross-sell/upsell opportunities **5. Integration & Automation:** - Sync subscription data to CRM/analytics platforms - Trigger workflows based on subscription details - Build custom reporting dashboards - Export subscription data for analysis **Response Format:** Returns an array of SubscriptionContractDetailsDTO objects: ```json [ { "id": 789, "subscriptionContractId": 5234567890, "status": "ACTIVE", "nextBillingDate": "2024-03-15T00:00:00Z", "billingInterval": "MONTH", "billingIntervalCount": 1, "deliveryInterval": "MONTH", "deliveryIntervalCount": 1, "currencyCode": "USD", "currentTotalPrice": "49.99", "customerId": 12345, "customerEmail": "customer@example.com", "lineItems": [...], "billingAddress": {...}, "shippingAddress": {...} }, {...} ] ``` **Response Scenarios:** **Customer with no subscriptions:** ```json [] ``` Returns empty array with 200 OK status (not an error). **Customer with multiple subscriptions:** Array contains multiple subscription objects, each representing a separate subscription contract. **Performance Considerations:** **Response Size:** - Each subscription object can be 5-50 KB depending on line items - Customer with 10 subscriptions: ~100-500 KB response - Consider pagination or filtering for customers with 20+ subscriptions **Query Performance:** - Typical response time: 200-500ms - Slower for customers with many subscriptions or complex products - Database query is optimized with indexed lookups **Best Practices:** 1. **Cache Results**: Cache response data to minimize API calls 2. **Filter Client-Side**: Filter/sort subscriptions on client after retrieval 3. **Selective Display**: Don't display all fields if not needed 4. **Handle Empty Array**: Always gracefully handle case with no subscriptions 5. **Optimize Images**: Product images can be large - lazy load if displaying **Data Freshness:** - Data is retrieved from Appstle database (not real-time Shopify query) - Updated via webhooks with < 1 second lag typically - Use sync endpoint if data appears stale **Security Notes:** - Customer ID is validated against authenticated shop - Returns only subscriptions belonging to specified customer - Cannot access customers from other shops - Sensitive payment details (full card numbers) are never returned **Comparison with Other Endpoints:** **vs. GET /subscription-customers/valid/{customerId}:** - This endpoint: Returns complete subscription details - Valid contracts endpoint: Returns only contract IDs - Use this when you need full subscription information **vs. GET /subscription-contract-details:** - This endpoint: Filtered by single customer - Contract details endpoint: Query across all customers with filters - Use this for customer-specific views **vs. GET /subscription-contracts/contract-external/{contractId}:** - This endpoint: All contracts for a customer - Contract external endpoint: Single contract with Shopify raw data - Use this for customer overview, other for detailed single contract **Authentication:** Requires valid X-API-Key header or api_key parameter (deprecated) ## OpenAPI ````yaml /subscription/admin-api-swagger.json get /api/external/v2/subscription-customers-detail/valid/{customerId} 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-customers-detail/valid/{customerId}: get: tags: - Customers - Subscription Contracts summary: Get detailed subscription information for a customer description: >- Retrieves comprehensive subscription contract details for a specific customer, including subscription status, products, billing information, delivery schedules, and more. This endpoint returns full subscription objects with all associated data, making it ideal for displaying subscription management interfaces and detailed analytics. **What This Endpoint Returns:** Unlike the contract IDs endpoint which returns only numeric IDs, this endpoint provides complete SubscriptionContractDetailsDTO objects for each of the customer's subscriptions. Each object contains all information needed to display and manage a subscription. **Data Included in Response:** **Subscription Identity:** - Subscription contract ID (Shopify numeric ID) - Subscription GraphQL ID (Shopify GID format) - Internal Appstle database ID - Contract creation date **Subscription Status & Lifecycle:** - Current status (ACTIVE, PAUSED, CANCELLED, EXPIRED, FAILED) - Status reason (why paused/cancelled) - Next billing date and time - Contract anchor date - Cancellation date (if applicable) - Current billing cycle number - Min/max cycle limits **Billing Configuration:** - Billing interval (WEEK, MONTH, YEAR) - Billing interval count (e.g., every 2 weeks) - Billing policy (pricing details) - Currency code - Recurring total price - Applied discounts and pricing policies **Delivery Configuration:** - Delivery interval (WEEK, MONTH, YEAR) - Delivery interval count - Delivery method (SHIPPING, PICK_UP, LOCAL_DELIVERY) - Delivery policy details - Delivery price **Products & Line Items:** - All subscribed products and variants - Product titles, SKUs, and images - Quantities per product - Individual line item prices - Product-specific discounts - Line item attributes and custom fields **Customer Information:** - Customer ID and GraphQL ID - Customer name and email - Customer acceptance status **Address Details:** - Billing address (full address object) - Shipping address (full address object) - Address validation status **Payment Information:** - Payment instrument type - Payment method details (card last 4, etc.) - Payment gateway used **Order & Fulfillment:** - Last order ID and details - Last order date - Order note - Fulfillment status **Additional Metadata:** - Custom note attributes - Tags and labels - Internal flags and settings - Selling plan ID and group ID - Shop domain **Use Cases:** **1. Customer Portal:** - Display all subscriptions on customer dashboard - Show subscription details page - Enable subscription management actions - Display upcoming order information **2. Admin Dashboard:** - View customer's complete subscription portfolio - Analyze subscription health and status - Identify at-risk or high-value subscriptions - Generate customer subscription reports **3. Customer Support:** - Quick access to all customer subscription details - Troubleshoot billing or delivery issues - Verify subscription configurations - Assist with subscription modifications **4. Analytics & Reporting:** - Calculate customer lifetime value - Analyze subscription mix per customer - Track subscription frequency distribution - Identify cross-sell/upsell opportunities **5. Integration & Automation:** - Sync subscription data to CRM/analytics platforms - Trigger workflows based on subscription details - Build custom reporting dashboards - Export subscription data for analysis **Response Format:** Returns an array of SubscriptionContractDetailsDTO objects: ```json [ { "id": 789, "subscriptionContractId": 5234567890, "status": "ACTIVE", "nextBillingDate": "2024-03-15T00:00:00Z", "billingInterval": "MONTH", "billingIntervalCount": 1, "deliveryInterval": "MONTH", "deliveryIntervalCount": 1, "currencyCode": "USD", "currentTotalPrice": "49.99", "customerId": 12345, "customerEmail": "customer@example.com", "lineItems": [...], "billingAddress": {...}, "shippingAddress": {...} }, {...} ] ``` **Response Scenarios:** **Customer with no subscriptions:** ```json [] ``` Returns empty array with 200 OK status (not an error). **Customer with multiple subscriptions:** Array contains multiple subscription objects, each representing a separate subscription contract. **Performance Considerations:** **Response Size:** - Each subscription object can be 5-50 KB depending on line items - Customer with 10 subscriptions: ~100-500 KB response - Consider pagination or filtering for customers with 20+ subscriptions **Query Performance:** - Typical response time: 200-500ms - Slower for customers with many subscriptions or complex products - Database query is optimized with indexed lookups **Best Practices:** 1. **Cache Results**: Cache response data to minimize API calls 2. **Filter Client-Side**: Filter/sort subscriptions on client after retrieval 3. **Selective Display**: Don't display all fields if not needed 4. **Handle Empty Array**: Always gracefully handle case with no subscriptions 5. **Optimize Images**: Product images can be large - lazy load if displaying **Data Freshness:** - Data is retrieved from Appstle database (not real-time Shopify query) - Updated via webhooks with < 1 second lag typically - Use sync endpoint if data appears stale **Security Notes:** - Customer ID is validated against authenticated shop - Returns only subscriptions belonging to specified customer - Cannot access customers from other shops - Sensitive payment details (full card numbers) are never returned **Comparison with Other Endpoints:** **vs. GET /subscription-customers/valid/{customerId}:** - This endpoint: Returns complete subscription details - Valid contracts endpoint: Returns only contract IDs - Use this when you need full subscription information **vs. GET /subscription-contract-details:** - This endpoint: Filtered by single customer - Contract details endpoint: Query across all customers with filters - Use this for customer-specific views **vs. GET /subscription-contracts/contract-external/{contractId}:** - This endpoint: All contracts for a customer - Contract external endpoint: Single contract with Shopify raw data - Use this for customer overview, other for detailed single contract **Authentication:** Requires valid X-API-Key header or api_key parameter (deprecated) operationId: getValidSubscriptionCustomerDetailsV2 parameters: - description: Customer Id in: path name: customerId required: true schema: format: int64 type: integer - description: API Key (Deprecated - Use Header X-API-Key instead) in: query name: api_key required: false schema: type: string - in: header name: X-API-Key required: false schema: type: string responses: '200': content: application/json: examples: Customer with active subscriptions: description: Customer with active subscriptions value: - billingInterval: MONTH billingIntervalCount: 1 currencyCode: USD currentCycle: 3 currentTotalPrice: '49.99' customerEmail: customer@example.com customerId: 12345 deliveryInterval: MONTH deliveryIntervalCount: 1 deliveryMethod: SHIPPING id: 789 nextBillingDate: '2024-03-15T00:00:00Z' shop: example-shop.myshopify.com status: ACTIVE subscriptionContractId: 5234567890 - billingInterval: WEEK billingIntervalCount: 2 currencyCode: USD currentTotalPrice: '24.99' customerEmail: customer@example.com customerId: 12345 id: 790 status: PAUSED subscriptionContractId: 5234567891 Customer with no subscriptions: description: Customer with no subscriptions value: [] schema: items: $ref: '#/components/schemas/SubscriptionContractDetailsDTO' type: array description: >- Successfully retrieved customer subscription details. Returns array of subscription objects (may be empty). '400': content: application/json: example: detail: Customer ID must be a valid positive integer status: 400 title: Invalid customer ID type: https://example.com/errors/bad-request description: Bad request - Invalid customer ID '401': content: application/json: example: detail: Valid X-API-Key header is required 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: Customer 12345 does not belong to your shop status: 403 title: Access denied type: https://example.com/errors/forbidden description: Forbidden - Customer does not belong to authenticated shop '429': content: application/json: example: detail: Too many requests. Please retry after 60 seconds. retryAfter: 60 status: 429 title: Rate limit exceeded type: https://example.com/errors/rate-limit description: Rate limit exceeded '500': content: application/json: example: detail: >- An unexpected error occurred while retrieving subscription details status: 500 title: Server error type: https://example.com/errors/internal-error description: Internal server error components: schemas: 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 ````